home *** CD-ROM | disk | FTP | other *** search
/ SGI Varsity Update 1998 August / SGI Varsity Update 1998 August.iso / docs6.4 / relnotes / WorkShop / ch5.z / ch5
Text File  |  1998-07-29  |  108KB  |  2,575 lines
  1.  
  2.  
  3.  
  4.                                   - 1 -
  5.  
  6.  
  7.  
  8.        5.  _K_n_o_w_n__P_r_o_b_l_e_m_s__a_n_d__W_o_r_k_a_r_o_u_n_d_s
  9.  
  10.        5.1  _W_o_r_k_S_h_o_p__D_e_b_u_g_g_e_r
  11.  
  12.           +o F90 support:  CVD does not provide sufficient support
  13.             for F90 specific constructs, such as array syntax,
  14.             dummy arguments, F90 pointers, and modules support.
  15.             Enhanced F90 support is a feature for the next release.
  16.  
  17.           +o Fix and continue:  Fix and continue is not supported
  18.             for applications that are compiled -n32.
  19.  
  20.           +o 6.5 pthread problem:  When doing process control, the
  21.             cvmain window's process control is really group, not
  22.             per thread.
  23.  
  24.           +o 6.5 pthread problem: cvmain is a bit fair-weathered
  25.             about the thread it focuses on.   That is, after doing
  26.             process control it can switch which thread is in focus.
  27.             The focused thread is not always the most interesting.
  28.             The intent is to allow 2 modes of operation.  One which
  29.             follows the 'most interesting' thread.  The other stays
  30.             focused on a particular thread until the user tells it
  31.             otherwise.  Using the cvmp/cvmain together helps
  32.             figuring out the most interesting process.
  33.  
  34.           +o 6.5 pthread problem: Not status-ing errored pthreads
  35.             correctly.
  36.  
  37.           +o The Execution View is always raised when switching
  38.             processes or threads.
  39.  
  40.           +o On the first print, cvd takes a very long time.  Also
  41.             if a user uses the call stack view or does a "where" it
  42.             takes a very long time.  For large applications the C++
  43.             expression evaluator sometimes requires excessive
  44.             amounts of resources to prepare for elaborate
  45.             evaluations. It does this despite the user potentially
  46.             only needing a basic expression evaluator.  (PV 509646)
  47.  
  48.             WORKAROUND : Use the following command in the commmand
  49.             window:  "set $dbxCEval = true".  This will cause cvd
  50.             to use the "dbx-like" expression evaluator instead of
  51.             the language specific one in the command window only.
  52.             The other views will still use the language specific
  53.             one.
  54.  
  55.             To use the "dbx-like" expression evaluator in all the
  56.             views use -xrm "*dbxCEval" on the cvd command line or
  57.             set the resource in your .Xdefaults file and reload by
  58.             doing a "xrdb -load .Xdefaults".
  59.  
  60.  
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.                                   - 2 -
  71.  
  72.  
  73.  
  74.             Note: The "dbx-like" expression evaluator will not
  75.             allow you to print member variables without
  76.             dereferencing the "this" pointer explicitly.  In the
  77.             future, the dbx-like expression evaluator will be
  78.             changed to understand the "this" ptr.
  79.  
  80.           +o When stepping into a function call the program stops at
  81.             the beginning of the function prolog instead of at the
  82.             end where the parameters are available.
  83.  
  84.             WORKAROUND : Do a next after stepping into a function
  85.             and the parameters will be updated.
  86.  
  87.           +o Doing a "step into" when stopped on a line with a call
  88.             to "new" like the following, will result in stepping
  89.             into "operator new(<stripped>)". In dbx the user steps
  90.             into the constructor for "foo".
  91.  
  92.                     _foo        = new foo ("foo");
  93.  
  94.             WORKAROUND : Hit the "return" button and do another
  95.             "step into".
  96.  
  97.           +o For some codes that use C++ templates users may get the
  98.             error when stopped in a C++ template function and
  99.             attempting to print member data : (PV 589766)
  100.  
  101.                     this = <syntax error>
  102.                     Line <line>: error(3339): "this" may only be
  103.             used inside a nonstatic
  104.             member function
  105.  
  106.             WORKAROUND : Use the following command in the commmand
  107.             window:  "set $dbxCEval = true".  This will cause cvd
  108.             to use the "dbx-like" expression evaluator instead of
  109.             the language specific one in the command window only.
  110.             The other views will still use the language specific
  111.             one.  This is fixed in the 7.3 C++ compiler.
  112.  
  113.             To use the "dbx-like" expression evaluator in all the
  114.             views use -xrm "*dbxCEval" on the cvd command line or
  115.             set the resource in your .Xdefaults file and reload by
  116.             doing a "xrdb -load .Xdefaults".
  117.  
  118.             Note: The "dbx-like" expression evaluator will not
  119.             allow you to print member variables without
  120.             dereferencing the "this" pointer explicitly.  In the
  121.             future, the dbx-like expression evaluator will be
  122.             changed to understand the "this" ptr.
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.                                   - 3 -
  137.  
  138.  
  139.  
  140.           +o Setting breakpoints in C++ template code that has been
  141.             implicitly included (see -auto_include on CC manpage)
  142.             and compiled -n32 is not supported.  (PV 449121)
  143.  
  144.             WORKAROUND : Users may attempt to recompile with
  145.             -no_auto_include.
  146.  
  147.           +o Users of the -mp compiler option in 7.2 compilers could
  148.             see that cvd may catch a SIGTERM signal from the
  149.             libmp.so library during termination of the program. The
  150.             user will see that the process stopped in
  151.             _sginap(<stripped>). (PV 559781)
  152.  
  153.             WORKAROUND : Users can set the environment variable
  154.             OMP_DYNAMIC to FALSE.   This will cause the library to
  155.             perform similar to what it did in the 7.1 compilers as
  156.             it relates to termination.
  157.  
  158.           +o Debugging of apps that use namespaces can lead to cvd
  159.             and dbx hanging, aborts and incorrect information being
  160.             generated.
  161.  
  162.           +o Source files that share the same header file but reside
  163.             in different DSO's and are compiled with the -gslim
  164.             option are not supported. (PV 570369)
  165.  
  166.           +o A program compiled with -n32 -g, unused variables can't
  167.             be clicked on
  168.              or printed in cvd. They could under -32 -g. (PV
  169.             596377)
  170.  
  171.           +o The 2.6.5 version of the WorkShop debugger has problems
  172.             evaluating references to class data members and the
  173.             "this" pointer in C++ programs compiled with the 7.1
  174.             and 7.0 versions of the C++ compiler.
  175.  
  176.             Workaround: You can recompile your code using the 7.2
  177.             or later version of the compiler.  These expressions
  178.             work correctly with the output of the 7.2 or later
  179.             compiler.  If you must debug 7.1 or 7.0 generated
  180.             programs or DSOs, use the following command in the
  181.             commmand window:  "set $dbxCEval = true". This will
  182.             allow you to reference class data members, but you will
  183.             have to reference them as "this->member".
  184.  
  185.           +o There is a limitation in the specification of the type
  186.             for a C++ exception trap.  The determination as to
  187.             whether a particular type has been thrown does not take
  188.             into account typedefs.  For example, given the type
  189.             definition:
  190.  
  191.  
  192.  
  193.  
  194.  
  195.  
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.                                   - 4 -
  203.  
  204.  
  205.  
  206.             ttttyyyyppppeeeeddddeeeeffff cccchhhhaaaarrrr ****SSSSttttrrrriiiinnnngggg;;;;
  207.  
  208.             setting the breakpoint:
  209.  
  210.             ssssttttoooopppp eeeexxxxcccceeeeppppttttiiiioooonnnn SSSSttttrrrriiiinnnngggg
  211.  
  212.             would have no effect.
  213.  
  214.             Workaround:  Use the base type specified in the typedef
  215.             when setting the breakpoint.
  216.  
  217.           +o After using cvd's Trap menu to change the setting of
  218.             Group Trap Default or Stop All Default, after an
  219.             extended period a dialog box may display the message
  220.             "Error: No debugger available to set trap modes".  This
  221.             can be ignored.
  222.  
  223.           +o Memory leak experiments might fail to unwind the stack
  224.             when particular functions are found in the stack (such
  225.             as usinit() from IRIX 6.2 libc or some libgl
  226.             functions).
  227.  
  228.           +o The views that do expression evaluation, Expression
  229.             View, the Evaluate Expression dialog box, Structure
  230.             Browser, Variable Browser, Array Visualizer, and the
  231.             Debugger command line cannot yet evaluate:
  232.  
  233.                - long double (C/C++) and unsigned variants
  234.  
  235.                - real * 16 (Fortran) and unsigned variants
  236.  
  237.                - complex *32 (Fortran) and unsigned variants
  238.  
  239.             Evaluation of these types is not available at this
  240.             time.  (Incident #206313)
  241.  
  242.           +o Making an interactive function call when the target
  243.             process is sleeping in a system call will cause the
  244.             target to fault. (Incident #223601)
  245.  
  246.           +o WorkShop does not accommodate text editors other than
  247.             Source View very well.
  248.  
  249.             Workaround:  Set the _e_d_i_t_o_r_C_o_m_m_a_n_d resource in the
  250.             _a_p_p-_d_e_f_a_u_l_t_s file to your desired editor.  For example,
  251.             set _e_d_i_t_o_r_C_o_m_m_a_n_d to _w_s_h -_c _v_i +%_d to run _v_i in a _w_s_h
  252.             window. You also need to set *_u_s_e_T_o_o_l_T_a_l_k to _F_a_l_s_e.
  253.  
  254.           +o The request to kill a process which has spawned child
  255.             processes (through _f_o_r_k(), _s_p_r_o_c(), or _s_p_r_o_c_s_p()),
  256.             followed by exiting _c_v_d, may not properly terminate the
  257.  
  258.  
  259.  
  260.  
  261.  
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268.                                   - 5 -
  269.  
  270.  
  271.  
  272.             descendant processes. The descendant processes may
  273.             continue to run after _c_v_d has exited.  (Incident
  274.             #206273)
  275.  
  276.             Workaround:  Kill all of the process group members with
  277.             the Multiprocess View as opposed to using the Main
  278.             View.  If any of the descendant processes were created
  279.             through a _f_o_r_k(), you will have had to direct the
  280.             Multiprocess View to attach to _f_o_r_k()ed process (see
  281.             ``Config: Preferences'' in the Multiprocess View).
  282.  
  283.           +o The Multiprocess View is known to occasionally not
  284.             display all process group members which _c_v_d is attached
  285.             to.  One condition where this problem occurs is when
  286.             the list of processes shown by the Multiprocess View is
  287.             frequently changing in a short span of time (for
  288.             example, processes are _f_o_r_k()ed which _e_x_e_c() and exit
  289.             shortly after they start).  (Incident #244782)
  290.  
  291.             Workaround:  Use of Stop in the Multiprocess View will
  292.             cause _c_v_d to stop all process group members and the
  293.             display should change to correctly list all processes.
  294.  
  295.           +o When _c_v_d is brought up on one member of a running
  296.             shared process group (see _s_p_r_o_c(2)), _c_v_d does not
  297.             identify and attach to all of the other processes which
  298.             are members of the shared process group. If you start
  299.             up the Multiprocess View you will only see the process
  300.             you started _c_v_d on.  The correct behavior from the
  301.             Multiprocess View would be to display all members of
  302.             the shared process group.  (Incident #179940)
  303.  
  304.             Workaround:  Use ``Process: Add'' in the Multiprocess
  305.             View to manually add each member of the shared process
  306.             group to the _c_v_d process group display by Multiprocess
  307.             View.
  308.  
  309.           +o Attempts to add a process which has been removed from
  310.             Multiprocess View may fail or lead to an abort of the
  311.             Multiprocess View.  (Incident #168934)
  312.  
  313.           +o Disassembly View sometimes has problems when two or
  314.             more DSOs have overlapping text.  In such cases,
  315.             Disassembly View displays only one of the DSOs from the
  316.             set whose text overlaps. This can happen to users who
  317.             are building their own DSOs.  Unfortunately _c_v_d does
  318.             not warn the user when this type of conflict occurs.
  319.             (Incident #204024)
  320.  
  321.           +o On attempting to locate the DSOs used by an executable,
  322.             _c_v_d uses the shell environment in which _c_v_d was
  323.  
  324.  
  325.  
  326.  
  327.  
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334.                                   - 6 -
  335.  
  336.  
  337.  
  338.             started, as opposed to the shell environment within the
  339.             Execution View.  This means that the value of
  340.             environment variables like LLLLDDDD____LLLLIIIIBBBBRRRRAAAARRRRYYYY____PPPPAAAATTTTHHHH which are
  341.             used by _c_v_d may not match the values in the shell where
  342.             the executable will be run.  When _c_v_d is using the
  343.             wrong values for environment variables like
  344.             LLLLDDDD____LLLLIIIIBBBBRRRRAAAARRRRYYYY____PPPPAAAATTTTHHHH, it may have trouble finding all of the
  345.             appropriate DSO symbol tables.  When _c_v_d has trouble
  346.             finding DSOs used by an executable it will display the
  347.             Library Search Path dialog to call attention to the
  348.             DSOs which could not be found. (Incidents #224125,
  349.             #236651)
  350.  
  351.             Workaround:  Use ``Admin: Library Search Path ...'' to
  352.             examine and set environment variables like
  353.             LLLLDDDD____LLLLIIIIBBBBRRRRAAAARRRRYYYY____PPPPAAAATTTTHHHH which control the identification of
  354.             DSOs.
  355.  
  356.           +o Watchpoints in _c_v_d may be defined with an address and
  357.             size or an expression.  If you attempt to watch an
  358.             expression which resides on the stack (for example, a
  359.             local variable) _c_v_d will not allow definition of the
  360.             trap.  _c_v_d will only watch expressions whose location
  361.             is within a mapping other than the stack.  (Incident
  362.             #197233)
  363.  
  364.             Workaround:  If you want to watch an expression which
  365.             resides on the stack, use the expression evaluator to
  366.             find the address of the expression and create the
  367.             watchpoint using the address.  Once the expression is
  368.             deallocated, the watchpoint should be removed to avoid
  369.             any confusion when the stack address is reused for some
  370.             other purpose later on in the execution.
  371.  
  372.           +o Process group watchpoints involving expressions are not
  373.             supported well.  If you create a watchpoint with a
  374.             command like ppppggggrrrrpppp wwwwaaaattttcccchhhh <<<<eeeexxxxpppprrrreeeessssssssiiiioooonnnn>>>>, the expression is
  375.             only evaluated once on one of the process group
  376.             members.  The evaluation is used to determine the
  377.             address and size of the watchpoint, and address and
  378.             size is used to create a watchpoint on each process
  379.             group member.  This will only work correctly if the
  380.             address and size of the expression is the same for each
  381.             process group member.  There is no workaround known for
  382.             this problem.  (Incident #143367)
  383.  
  384.           +o The Trap Manager fails to properly define watchpoints
  385.             on 64-bit addresses.  The address typed in the
  386.             ``Trap:'' field is corrupted and either a watchpoint is
  387.             created on the wrong address or an invalid address
  388.             error is reported (_W_a_t_c_h_p_o_i_n_t _a_d_d_r_e_s_s _r_a_n_g_e _i_n_c_l_u_d_e_s _a_n
  389.  
  390.  
  391.  
  392.  
  393.  
  394.  
  395.  
  396.  
  397.  
  398.  
  399.  
  400.                                   - 7 -
  401.  
  402.  
  403.  
  404.             _i_n_v_a_l_i_d _v_i_r_t_u_a_l _a_d_d_r_e_s_s.).  (Incident #235635)
  405.  
  406.             Workaround: The command line interface panel in the _c_v_d
  407.             Main View can be used in place of the Trap Manager to
  408.             enter the watchpoint command.
  409.  
  410.           +o A write watchpoint may fail to fire when the write
  411.             occurs within a syscall.  For example, a write
  412.             watchpoint on one word within a buffer written by read
  413.             may fail to fire.
  414.  
  415.             Workaround:  Define the watchpoint to cover the entire
  416.             data structure as opposed to a subset of the structure.
  417.             For example, define the watchpoint over the entire
  418.             buffer being handed to read as opposed to a single
  419.             word.
  420.  
  421.           +o An attempt to step into the first call to an external
  422.             function will behave like a step over.  The first call
  423.             to an external function invokes rld to resolve the
  424.             function address.  When this occurs the request to step
  425.             into the call will look like a step over to the user.
  426.             (Incident #147302)
  427.  
  428.             Workaround: Either set the environment variable
  429.             _L_D__B_I_N_D__N_O_W to 1 in the Execution View prior to running
  430.             the program (see _r_l_d(1)) or use function entry
  431.             breakpoints.
  432.  
  433.           +o Traps placed within a parallel Fortran DO loop, created
  434.             with the C$DOACROSS compiler directive, fail to work
  435.             correctly.  Although the traps appear to be placed
  436.             correctly on 6.0 systems, the process will not stop on
  437.             the traps. (Incident #20818)
  438.  
  439.             Workaround:  On a 6.0 system _d_b_x can be used
  440.             successfully to place traps within the loop.
  441.  
  442.           +o The Fortran intrinsics _c_h_a_r, _z_e_x_t, _s_e_c_o_n_d_s, _m_a_l_l_o_c, and
  443.             _e_p are not supported.  (Incident #206293)
  444.  
  445.           +o The debugger does not understand external or intrinsic
  446.             statements in the Fortran program.  If the program has
  447.             a function by the same name as an intrinsic function,
  448.             evaluating an expression involving that function will
  449.             always cause the program function to be called.
  450.  
  451.           +o Some of the intrinsics (_s_q_r_t, _e_x_p, _l_o_g, _l_o_g_1_0, _s_i_n,
  452.             _c_o_s, _t_a_n, _a_s_i_n, _a_c_o_s, _a_t_a_n, _s_i_n_h, _c_o_s_h, _t_a_n_h) do not
  453.             give the correct results when the debugged executable
  454.             is linked with _l_i_b_m._s_o.  This is because of entry
  455.  
  456.  
  457.  
  458.  
  459.  
  460.  
  461.  
  462.  
  463.  
  464.  
  465.  
  466.                                   - 8 -
  467.  
  468.  
  469.  
  470.             points with similar names in _l_i_b_m._s_o.
  471.  
  472.             Workaround: Use a specific intrinsic name.  For
  473.             example, _s_i_n(_r_1) where _r_1 is real will produce
  474.             incorrect results.  On the otherhand, _d_s_i_n(_d_f_l_o_a_t(_r_1))
  475.             will give correct results, with the results being a
  476.             _r_e_a_l *_8 quantity.
  477.  
  478.           +o Stopping in the entry prologue of a function (before
  479.             the first user statement) in a Fortran program and
  480.             evaluating an expression that involves an adjustable
  481.             array or displaying an adjustable array in the Array
  482.             Visualizer will not work correctly.  (Incident #206264)
  483.  
  484.             Workaround: Step to the first user statement and
  485.             evaluate the expression.
  486.  
  487.           +o When stopped in a Fortran function/subprogram that has
  488.             alternate entry points, the debugger will not list all
  489.             the arguments of the subprogram and their values
  490.             correctly.  (Incident #164327)
  491.  
  492.           +o For global lookups, _c_v_d acts as though all DSOs are
  493.             built ----BBBB ssssyyyymmmmbbbboooolllliiiicccc.  If a process is stopped within a
  494.             DSO and the user asks _c_v_d to lookup a global variable
  495.             or function, _c_v_d will always look within the DSO before
  496.             it considers the main program or any other DSO.  In
  497.             effect, _c_v_d is acting as if each DSO has been built
  498.             with ----BBBB ssssyyyymmmmbbbboooolllliiiicccc.  (Incidents #173343)
  499.  
  500.           +o Interactive calls to inline member functions of C++
  501.             classes is not supported.
  502.  
  503.           +o The display format for describing an array pointer
  504.             types is incorrect.  For example, an array of
  505.             double(*)[2] is expressed as double[]*.
  506.  
  507.           +o Elements of Fortran arrays with more than 6 dimensions
  508.             (or 5 dimensions, if the element type is character
  509.             string) cannot be referenced.
  510.  
  511.           +o C++ objects containing virtual base classes do not
  512.             display correctly in the expression evaluator.
  513.             (Incident #190170)
  514.  
  515.           +o _c_v_p_c_s can stack trace through assembler alternate entry
  516.             functions only when they are at the same address as the
  517.             main entry point.  Assembler functions with arbitrary
  518.             alternate entry points will produce incorrect stack
  519.             trace.
  520.  
  521.  
  522.  
  523.  
  524.  
  525.  
  526.  
  527.  
  528.  
  529.  
  530.  
  531.  
  532.                                   - 9 -
  533.  
  534.  
  535.  
  536.           +o When the Trap Manager is invoked, traps are
  537.             automatically loaded from the ._c_v_T_r_a_p_M_g_r file if one
  538.             exists.  However, these traps are reloaded if the Trap
  539.             Manager is closed and restarted.  (Incident #79217)
  540.  
  541.             Workaround: The Trap Manager should either be left
  542.             running or the default traps should be stored in a
  543.             different file and reloaded manually when desired.
  544.  
  545.           +o In general, when a write watchpoint fires, the write is
  546.             simulated by the debugger to show the new value before
  547.             any trap conditional is evaluated.  The four exceptions
  548.             for this case are the SC, SCD, SDL, and SDR
  549.             instructions.  (Incident #250036)
  550.  
  551.           +o A kernel bug prevents watchpoints from firing reliably
  552.             for members of share process groups (such as Power
  553.             Fortran or Power C programs).  Watchpoints work
  554.             reliably for non-shared text and data segments in each
  555.             individual process.
  556.  
  557.           +o If you stop a process through job control, the debugger
  558.             may not display an accurate status of the process, and
  559.             process control requests do not take effect until the
  560.             process is resumed through job control.  A process is
  561.             stopped through job control with <Ctrl-Z> from the
  562.             shell or when it receives one of the signals: SIGSTOP,
  563.             SIGTSTP, SIGTTIN, and SIGTTOU.  A process is resumed
  564.             through job control with _f_g and _b_g from the shell or
  565.             when it receives the signal SIGCONT.  If a running
  566.             process is stopped through job control, the debugger
  567.             continues to show that the process is running.  When
  568.             attaching to a process stopped through job control, the
  569.             debugger shows that the process is stopped.  (Incident
  570.             #167693)
  571.  
  572.           +o For instrumented executables (used for performance
  573.             analysis), stack frame unwinding may be incomplete when
  574.             stopped in a signal handler; the unwinding may stop
  575.             prematurely after the ``_sigtramp'' frame.  (Incident
  576.             #71307)
  577.  
  578.             Workaround: A full stack trace may be maintained by
  579.             returning past the ``_sigtramp'' frame.
  580.  
  581.           +o The demo program _j_e_l_l_o cannot be built as described in
  582.             the tutorial without the library /_u_s_r/_l_i_b/_l_i_b_g_l._s_o.
  583.  
  584.             Workaround:  This library should be installed when IRIX
  585.             is installed (eoe1.sw.gfx_lib subsystem).
  586.  
  587.  
  588.  
  589.  
  590.  
  591.  
  592.  
  593.  
  594.  
  595.  
  596.  
  597.  
  598.                                   - 10 -
  599.  
  600.  
  601.  
  602.           +o Processes that use the blocking capabilities as
  603.             provided by _b_l_o_c_k_p_r_o_c(2) may not terminate as expected
  604.             upon completion of a debug session.  Such processes are
  605.             left in a blocked state with a SIGKILL pending.
  606.  
  607.             Workaround:  These processes can be terminated with
  608.             _k_i_l_l(1).
  609.  
  610.           +o The modification of an inactive trap will cause the
  611.             trap to become active.  You will have to toggle the
  612.             active button next to the trap description in order to
  613.             deactivate the trap.  (Incident #190278)
  614.  
  615.           +o There is a case where the path remapping component of
  616.             WorkShop will find the wrong file.  When _c_v_d is stopped
  617.             and started multiple times, and ``Admin:Exit'' was used
  618.             to exit _c_v_d, the path remapping component will retain
  619.             entries in its Substitution Set from each debugging
  620.             session (see ``Admin:Project:Remap Paths...'').  The
  621.             path remapping component of _c_v_d is implemented as a
  622.             separate process and the ``.'' entry in the
  623.             Substitution Set refers to the directory in which the
  624.             process was started, typically the directory were the
  625.             first _c_v_d was started.
  626.  
  627.             Workaround: Use ``Admin:Project:Exit'' in place of
  628.             ``Admin:Exit''.  This will force the path remapping
  629.             process to terminate on each exit of _c_v_d.
  630.  
  631.           +o By default the debugger will not attach to a _f_o_r_k()ed
  632.             process unless the fork occurs during an interactive
  633.             function call.  If you have used the Multiprocess View
  634.             preferences dialog to prevent a forked child from being
  635.             resumed, and you make an interactive function call will
  636.             leads to a call on fork, the child process will be left
  637.             stopped on exit from fork.  You must now use the
  638.             Multiprocess View to resume the child process.
  639.             (Incident #190308)
  640.  
  641.           +o Fortran COMMON block members that are at an offset
  642.             greater than 8 Megabytes from the start of the common
  643.             block will not be evaluated correctly in an expression.
  644.  
  645.           +o When using the Switch Process dialog to attach to an
  646.             existing process, don't attach to one of the CaseVision
  647.             or WorkShop processes (e.g. _c_v_p_a_t_h_R_e_m_a_p, _c_v_m_a_i_n) or the
  648.             environment may hang. Should this happen, kill the
  649.             _c_v_m_a_i_n process and start over.
  650.  
  651.           +o Occasionally, _c_v_m_a_i_n will dump core at startup if you
  652.             have an executable with a mismatched core file and your
  653.  
  654.  
  655.  
  656.  
  657.  
  658.  
  659.  
  660.  
  661.  
  662.  
  663.  
  664.                                   - 11 -
  665.  
  666.  
  667.  
  668.             NetLS license is within 90 days of expiring.  If this
  669.             happens, restart _c_v_d.
  670.  
  671.           +o The main window's command line interface panel will
  672.             only display the first 100 elements of an array.  There
  673.             is no way to change this behavior.  (Incident #250028)
  674.  
  675.             Workaround:  The best way to examine an array is the
  676.             Array Browser.
  677.  
  678.           +o The command line interface panel in the _c_v_d Main View
  679.             may fail to evaluate expressions when the process is
  680.             stopped and the language of the current context is
  681.             Assembler. (Incident #246294)
  682.  
  683.             Workaround: The Expression View can be used in place of
  684.             the command line interface panel.
  685.  
  686.           +o After a process has stopped, an expression value may
  687.             become invalid due to evaluation of another expression
  688.             or use of debugger commands which can lead to
  689.             modification of expression values.  An example would be
  690.             the value of a variable displayed in Expression View
  691.             which is not recalculated after the variable is updated
  692.             with the _a_s_s_i_g_n command in the command line interface
  693.             panel.  (Incident #247050)
  694.  
  695.             Workaround: Force the value of the expression to be
  696.             recalculated by retyping the expression.
  697.  
  698.           +o The Array Visualizer will no longer implicitly use _t_h_i_s
  699.             on a C++ program.  When attempting to display the
  700.             member of a class you will have to explicitly include
  701.             _t_h_i_s-> along with the name of the member.  (Incident
  702.             #248882)
  703.  
  704.           +o Use of the division, and modulus operators in the
  705.             ``Indexing Expression:'' field of the Array Visualizer
  706.             may not work correctly on 64-bit executables.
  707.             (Incident #249262)
  708.  
  709.           +o _c_v_d may not list all the member functions of a class
  710.             correctly when the class and its member functions are
  711.             built into a separate DSO.  (Incident #249733)
  712.  
  713.           +o _c_v_d cannot evaluate expressions involving local classes
  714.             (classes that are defined inside of a function).
  715.             (Incident #212268)
  716.  
  717.           +o The Query menu within _c_v_d will fail to operate
  718.             correctly if _c_v_d was attached to a running process (ccccvvvvdddd
  719.  
  720.  
  721.  
  722.  
  723.  
  724.  
  725.  
  726.  
  727.  
  728.  
  729.  
  730.                                   - 12 -
  731.  
  732.  
  733.  
  734.             ----ppppiiiidddd ............)  or if _c_v_s_t_a_t_i_c is started by hand (``Admin:
  735.             Launch Tool -> Static Analyzer'').   (Incident #238595)
  736.  
  737.           +o A trap at the closing brace of a C/C++ function may not
  738.             be defined properly.  This is known to occur when the
  739.             last statement of the function is a return statement.
  740.             When this problem occurs the trap is defined on a
  741.             source line following the closing brace, typically the
  742.             opening brace of the next function.
  743.  
  744.             Workaround: Place the trap on the source line
  745.             containing the return statement as opposed to the line
  746.             containing the closing brace.   (Incident #277136)
  747.  
  748.           +o _c_v_d may close file descriptors it should leave open in
  749.             the _r_u_n command.  All file descriptors at 3 and above
  750.             are closed by _c_v_d.   (Incident #277295)
  751.  
  752.           +o The _c_v_p_c_s component of _c_v_d is known to occasionally
  753.             abort on erroneous expression evaluation requests from
  754.             the one-time expression evaluation component of _c_v_d.
  755.             (Incident #282160)
  756.  
  757.           +o Evaluation of a C++ expression which contains a
  758.             variable whose name is the same as that of a structure
  759.             may lead to an erroneous error.   (Incident #286949)
  760.  
  761.           +o Under some conditions, on some R5K Indy and O2
  762.             machines, a hardware problem may cause traps to not
  763.             fire the first time they are encountered.  Rerun often
  764.             works around the problem (Incident #439770).
  765.  
  766.        5.1.1  _D_e_b_u_g_g_i_n_g__P_r_o_g_r_a_m__G_r_o_u_p_s__I_n_c_l_u_d_i_n_g__a__S_e_t_-_u_i_d__P_r_o_g_r_a_m
  767.        Because of standard IRIX security policies, the debugger can
  768.        not debug a program running as another user (unless you are
  769.        logged in as _r_o_o_t).  This restriction applies even to system
  770.        programs which are set-UID, and even when all you want to do
  771.        with the set-UID program is debug something that it in turn
  772.        runs.  It is common to use the system-provided set-UID
  773.        program _x_w_s_h (or _w_i_n_t_e_r_m, which in turn runs _x_w_s_h) in this
  774.        way.
  775.  
  776.        There are two basic ways to deal with this problem.  You can
  777.        become _r_o_o_t before starting your debugging session, which
  778.        grants you all necessary access rights (but may be
  779.        infeasible for your application or situation).  Or, you can
  780.        arrange to use a non-set-UID copy of the intermediary
  781.        program, for example with _c_h_m_o_d, or by making a copy of the
  782.        program with _c_p.
  783.  
  784.  
  785.  
  786.  
  787.  
  788.  
  789.  
  790.  
  791.  
  792.  
  793.  
  794.  
  795.  
  796.                                   - 13 -
  797.  
  798.  
  799.  
  800.        There is also a bug in the IRIX 6.0 version of _x_w_s_h which
  801.        makes it unreliable if run non-set-UID.  You may be able to
  802.        use _x_t_e_r_m instead of _x_w_s_h for these applications, for
  803.        example by using _w_i_n_t_e_r_m and setting the environment
  804.        variable WWWWIIIINNNNTTTTEEEERRRRMMMM to xxxxtttteeeerrrrmmmm before starting your debugging
  805.        session (and providing a non-set-UID copy of _x_t_e_r_m).
  806.  
  807.        If your application depends on features of _x_w_s_h, can not use
  808.        _x_t_e_r_m instead, and can not be run as _r_o_o_t, then this
  809.        procedure will generally ensure that you can debug as non-
  810.        root:
  811.  
  812.           +o Make a non-set-uid copy of _x_w_s_h (ccccpppp ////uuuussssrrrr////ssssbbbbiiiinnnn////xxxxwwwwsssshhhh ....).
  813.  
  814.           +o Start several _x_w_s_h or _x_t_e_r_m windows, as the user who
  815.             will be doing the debugging.  Exit them all.  It is
  816.             important that they all be started together, all be
  817.             running at once, and then be exited immediately before
  818.             the debugging session begins.
  819.  
  820.           +o Debug your application.
  821.  
  822.           +o Set one or more breakpoints by function name ("stop in
  823.             main"), in the syscall panel, or with the ``Traps: Stop
  824.             at Function Entry'' menu - not by clicking in the glyph
  825.             bar of the main window.  (Traps set on a particular
  826.             source line, as by clicking, are not copied from one
  827.             program to the next.)
  828.  
  829.           +o Bring up the MPView, from the Admin menu.
  830.  
  831.           +o Be sure all the "copy traps...." boxes are checked in
  832.             its configuration dialog.
  833.  
  834.           +o Run your application, using MPView's ``Continue''
  835.             button as necessary and watching MPView for the
  836.             appearance of your subprocess.  Double-click it to
  837.             launch a debugger on it.
  838.  
  839.  
  840.        5.2  _W_o_r_k_S_h_o_p__F_i_x_+_C_o_n_t_i_n_u_e
  841.  
  842.        5.2.1  _L_i_m_i_t_a_t_i_o_n_s__o_f__F_i_x_+_C_o_n_t_i_n_u_e
  843.  
  844.           +o You cannot add or delete global variables or functions.
  845.  
  846.           +o You are restricted to editing the bodies of existing
  847.             non-inline functions. If you attempt to edit an inline
  848.             function, no warnings are emitted, but the results are
  849.             unpredictable.
  850.  
  851.  
  852.  
  853.  
  854.  
  855.  
  856.  
  857.  
  858.  
  859.  
  860.  
  861.  
  862.                                   - 14 -
  863.  
  864.  
  865.  
  866.             Incident 240481
  867.  
  868.           +o You cannot modify a function while the program is
  869.             sleeping in a system call, or is stopped on entry to a
  870.             system call.  The debugger will detect this condition
  871.             and prevent you from loading the modified function
  872.             until you return from the system call.
  873.  
  874.             You can set a trap on exit from the system call using
  875.             the System Call panel of cvd and continue the program
  876.             in order to get to a point where function loading is
  877.             allowed.
  878.  
  879.             Incident 244664
  880.  
  881.           +o The Multiprocess View capability of the debugger does
  882.             not interact well with the Fix and Continue feature.
  883.             sproc'ed and forked processes inherit the new
  884.             redefinition of the function.  However, when starting a
  885.             debugger session on the new process, the debugger is
  886.             not aware that the process contains function
  887.             redefinitions.  This means that there is no way to
  888.             deactivate the new definition in the new process after
  889.             a sproc() or a fork(). If the new function definition
  890.             is not desired in the new process, it is necessary to
  891.             stop the process on entry to fork() or sproc(),
  892.             deactivate the modified function and activate it again
  893.             on exit from fork() or sproc().
  894.  
  895.        5.2.2  _K_n_o_w_n__P_r_o_b_l_e_m_s__w_i_t_h__F_i_x__a_n_d__C_o_n_t_i_n_u_e
  896.  
  897.           +o The Disassembly View has not been updated to work with
  898.             the Fix and Continue feature. As a result, you will
  899.             notice the following behavior when viewing a modified
  900.             function in Disassembly View:
  901.  
  902.                +o The filename displayed is incorrect, and reflects
  903.                  the name of the temporary file used by the Fix and
  904.                  Continue mechanism.
  905.  
  906.                +o The assembly instructions are not interleaved with
  907.                  the source code.
  908.  
  909.                +o The line numbers shown in Disassembly View do not
  910.                  reflect the line numbers used in the rest of the
  911.                  debugger (i.e., instead of "7.3", the Disassembly
  912.                  View will say line "9").
  913.  
  914.             Incident 243635
  915.  
  916.  
  917.  
  918.  
  919.  
  920.  
  921.  
  922.  
  923.  
  924.  
  925.  
  926.  
  927.  
  928.                                   - 15 -
  929.  
  930.  
  931.  
  932.           +o The initialization value of local statics in C may not
  933.             be modified.  If you make such a change, it will
  934.             silently be ignored. Since you are permitted to add new
  935.             local statics, you can accomplish a change of the
  936.             initialization value using the following workaround:
  937.  
  938.             /* Original function */
  939.             void f() {
  940.                static int i = 0; /* oops. This should be -1 */
  941.             }
  942.  
  943.             /* New function */
  944.             void f() {
  945.                static int i = 0; /* oops. This should be -1 */
  946.                static int first_time = 1;
  947.                if (first_time) {
  948.                   i = -1;
  949.                   first_time = 0;
  950.                }
  951.             }
  952.  
  953.             Incident 246306
  954.  
  955.           +o In C it is legal to call a function without declaring
  956.             it, and later declare the function to be static. For
  957.             example:
  958.  
  959.                main(){
  960.                   f();
  961.                   return 0;
  962.                }
  963.  
  964.                static int f(){
  965.                }
  966.  
  967.             Since the Fix and Continue feature will only compile
  968.             "main", and since there is no declaration for "f", the
  969.             compiler will assume that "f" is an external function,
  970.             and there will subsequently by a "Load Error" in the
  971.             Interpreter Message window since the runtime loader
  972.             will be unable to find an external definition for "f".
  973.             The workaround is to make sure the compiler knows that
  974.             "f" is static when you use modify "main" during a Fix
  975.             and Continue operation:
  976.  
  977.                main(){
  978.                   static int f();
  979.                   f();
  980.                   return 0;
  981.                }
  982.  
  983.  
  984.  
  985.  
  986.  
  987.  
  988.  
  989.  
  990.  
  991.  
  992.  
  993.  
  994.                                   - 16 -
  995.  
  996.  
  997.  
  998.             Incident 246317
  999.  
  1000.           +o When executing an older version of a function, you will
  1001.             see the most recent source in the source window.
  1002.             Consequently the line numbers, PC highlight, and
  1003.             breakpoints displayed may be on the wrong lines.
  1004.  
  1005.           +o If you open a source file using "Source:Open...", the
  1006.             source file is opened in "Editable" mode by default.
  1007.             This prevents Fix and Continue operations on the file,
  1008.             and you will see the "Fix+Continue" button grayed out.
  1009.             If you wish to use Fix and Continue on this file, use
  1010.             the "Source:Make Read Only" menu option. If you use
  1011.             "Source:Open..." to open a source file in which you
  1012.             have previously modified functions, the modified
  1013.             functions will not be highlighted while the source file
  1014.             is editable.
  1015.  
  1016.             If you save a file in which some changes were made
  1017.             using Fix and Continue, and some changes were made
  1018.             using "Source:Open...", confusion may occur.  You can
  1019.             workaround this by using "Source:Make Editable"
  1020.             followed by "Source:Make Read Only". Another workaround
  1021.             is to switch to some other file and then switch back to
  1022.             the current file. Switching back can be accomplished by
  1023.             making the process stop in the file or by using
  1024.             "Source:Open..." followed by "Source:Make Read Only".
  1025.  
  1026.             Incidents 243627, 243629, 248842
  1027.  
  1028.           +o If you are stopped in a program, and you modify a
  1029.             function which is not the one you are stopped in, after
  1030.             the "Parse And Load" completes your source is
  1031.             repositioned at the line on which you are stopped,
  1032.             rather than at the function you just modified.
  1033.  
  1034.             Incident 246739
  1035.  
  1036.           +o The Fix and Continue mechanism does not currently check
  1037.             to make sure that a file has not been modified after it
  1038.             was last compiled. If you modify a function using Fix
  1039.             and Continue, save the source back to its original
  1040.             file, and forget to rebuild your application after
  1041.             exiting the debugger, you will see unpredictable result
  1042.             if you re-enter the debugger and attempt to use Fix and
  1043.             Continue. For example, the debugger may think that
  1044.             function "f" is on lines 15 to 20, whereas your
  1045.             previous changes may have repositioned the function on
  1046.             lines 17 to 22. When you select "Fix+Continue:Edit" if
  1047.             you notice that the edit region does not cover the
  1048.             entire body of the function, you should exit the
  1049.  
  1050.  
  1051.  
  1052.  
  1053.  
  1054.  
  1055.  
  1056.  
  1057.  
  1058.  
  1059.  
  1060.                                   - 17 -
  1061.  
  1062.  
  1063.  
  1064.             debugger and rebuild your application.
  1065.  
  1066.             Incident 245098
  1067.  
  1068.           +o If your original build compiled multiple files with a
  1069.             single command line, this same command line will be run
  1070.             when using Fix and Continue to modify a function in any
  1071.             of those files, causing unnecessary recompilations of
  1072.             the other files, and possibly erroneous results.  For
  1073.             best results, compile files one at a time using the -c
  1074.             option of the compiler.  If this is not possible, use
  1075.             the Build Environment view to modify the command line
  1076.             and remove all file names from it (Fix and Continue
  1077.             will add in the file actually being compiled
  1078.             automatically).
  1079.  
  1080.           +o When you use the "Fix and Continue->Edit" menu item,
  1081.             the region you are allowed to edit begins with the line
  1082.             containing the first "{" of your function.  This line
  1083.             would include the line containing the function and
  1084.             parameter declaration, for the coding style shown
  1085.             below:
  1086.  
  1087.                void f(int y){
  1088.                   /* .... */
  1089.                }
  1090.  
  1091.             In such cases, you should make sure you do not change
  1092.             the function name and parameter profile. The
  1093.             implementation does not currently check that you do not
  1094.             make such changes, but you may receive a message like
  1095.             this:
  1096.  
  1097.                No reply from PCS;
  1098.                unknown error while loading dso for the modified function
  1099.  
  1100.             Incident 245299
  1101.  
  1102.           +o If a "stop exit" trap is placed in a function, and Fix
  1103.             and Continue is used on the function after hitting the
  1104.             exit trap, then if execution can continue in the new
  1105.             function, the PC is moved back to the beginning of the
  1106.             line (it is in the epilogue, at the "jr ra"
  1107.             instruction). This means the epilogue is re-executed.
  1108.             This could cause problems if the stack pointer has
  1109.             already been decremented, because now it will get
  1110.             decremented twice. Your program may occasionally work
  1111.             if the stack decrement happens to be after the "jr ra"
  1112.             instruction. The implementation currently does not
  1113.             always detect this condition.
  1114.  
  1115.  
  1116.  
  1117.  
  1118.  
  1119.  
  1120.  
  1121.  
  1122.  
  1123.  
  1124.  
  1125.  
  1126.                                   - 18 -
  1127.  
  1128.  
  1129.  
  1130.             The workaround is to reposition the PC at the "jr ra"
  1131.             using PC->JumpTo after your F&C has completed.
  1132.  
  1133.             F&C and templates
  1134.  
  1135.           +o Using F&C on functions which use templates are not
  1136.             completely supported in this release. Typically, if the
  1137.             change involves instantiating new functions, then such
  1138.             a  change is not supported in this release. If the
  1139.             process is stopped when this change is made, the F&C
  1140.             error message window will display the error message
  1141.             from rld under the PCS error messages. Otherwise, views
  1142.             would temporarily show that the change is ok, but when
  1143.             the process is run later , load error message will be
  1144.             reported and the change is switched back to edited
  1145.             state.
  1146.  
  1147.             The error message would be something like:  :
  1148.             26095:/tmp_mnt/hosts/xanadu/usr/people/pal/kim/mnm:
  1149.             rld: Fatal Error: unresolvable symbol in
  1150.             /var/tmp/cvintp26042/cvfn1.3.so:
  1151.                     static_allocator__15vector__pt__2_i
  1152.  
  1153.             Incident 249309
  1154.  
  1155.  
  1156.        5.3  _W_o_r_k_S_h_o_p__M_o_t_i_f__A_n_a_l_y_z_e_r
  1157.  
  1158.           +o If you create traps in the Motif Analyzer window using
  1159.             the Breakpoints examiner, trap items will appear in the
  1160.             Trap Manager window of the WorkShop Debugger.  These
  1161.             items will be labeled "MotifBreak."  You should not
  1162.             attempt to modify or delete these traps using the Trap
  1163.             Manager.  Instead, always use the Breakpoints examiner
  1164.             to modify or delete your Motif-related breakpoints.
  1165.  
  1166.           +o If you install the MegaDev.sw.motif subsystem and then
  1167.             reinstall the WorkShop.sw.cvd subsystem, the "Motif
  1168.             Analyzer" item will disappear from the Views menu in
  1169.             the WorkShop Debugger.  Reinstalling the
  1170.             MegaDev.sw.motif subsystem will correct the problem.
  1171.  
  1172.           +o If you install the WorkShop.sw.cvd and MegaDev.sw.motif
  1173.             subsystems, and then remove only the MegaDev.sw.motif
  1174.             subsystem, the "Motif Analyzer" menu item will still
  1175.             exist in the Views menu in the WorkShop Debugger.
  1176.             Selecting this menu item, however, will result in an
  1177.             error dialog.  Reinstalling the WorkShop.sw.cvd
  1178.             subsystem will remove the item from the Views menu.
  1179.  
  1180.  
  1181.  
  1182.  
  1183.  
  1184.  
  1185.  
  1186.  
  1187.  
  1188.  
  1189.  
  1190.  
  1191.  
  1192.                                   - 19 -
  1193.  
  1194.  
  1195.  
  1196.           +o Occasionally, the Motif Analyzer display will remain
  1197.             inactive after switching between processes using
  1198.             WorkShop's "Switch Process" or "Switch Executable" menu
  1199.             items, or when rerunning the process after changing the
  1200.             command arguments.  If this happens, close the Motif
  1201.             Analyzer window and use WorkShop's Views menu to bring
  1202.             it up again.
  1203.  
  1204.           +o If your application connects to a remote X display and
  1205.             you do not set LD_LIBRARY_PATH to include
  1206.             /usr/lib/WorkShop/Motif, any Editres-type operations
  1207.             (e.g. widget select and widget tree) will operate on
  1208.             the local display and not work correctly.  Either run
  1209.             your program using the local X display or change
  1210.             LD_LIBRARY_PATH as advised.
  1211.  
  1212.           +o A small number of applications build their widget
  1213.             hierarchy in such a way that Editres widget selection
  1214.             operations cause them to exit with an X error.  If your
  1215.             application falls into this category, then using the
  1216.             Motif Analyzer widget select functionality will cause
  1217.             the same thing to happen.
  1218.  
  1219.  
  1220.        5.4  _W_o_r_k_S_h_o_p__B_u_i_l_d__A_n_a_l_y_z_e_r
  1221.  
  1222.        If target or dependency names are specified using
  1223.        parentheses to denote files stored within an archive
  1224.        library, _c_v_b_u_i_l_d will use a single node to represent the
  1225.        archive library, rather than individual nodes for each file
  1226.        within it.
  1227.  
  1228.  
  1229.        5.5  _W_o_r_k_S_h_o_p__S_t_a_t_i_c__A_n_a_l_y_z_e_r
  1230.  
  1231.        5.5.1  _G_e_n_e_r_a_l__K_n_o_w_n__P_r_o_b_l_e_m_s
  1232.  
  1233.           +o The Directory Query "List Files" works only when the
  1234.             query target is a full path name of a directory.  For
  1235.             example, it works on the target "/usr/include", but not
  1236.             on a target like "include".
  1237.  
  1238.             Workaround: Select the General Option "Full Pathnames".
  1239.             Then any directory names displayed will contain full
  1240.             paths, and so the "List Files" query will cork on them
  1241.             correctly.
  1242.  
  1243.           +o If you use _c_v_s_t_a_t_i_c to analyze a fileset and then
  1244.             change one or more of the header files included by the
  1245.             files in the fileset, rescanning the fileset will not
  1246.             detect the change.  Rescanning only detects changes to
  1247.  
  1248.  
  1249.  
  1250.  
  1251.  
  1252.  
  1253.  
  1254.  
  1255.  
  1256.  
  1257.  
  1258.                                   - 20 -
  1259.  
  1260.  
  1261.  
  1262.             source files listed in the fileset.  Similarly, if you
  1263.             remove a source file from a fileset and rescan, the
  1264.             header files included by that file are not removed from
  1265.             the database. (Incident #179731)
  1266.  
  1267.             Workaround: If you have changed one or more files in a
  1268.             fileset (or included by files in a fileset), you can
  1269.             get a consistent database by selecting ``Force Scan''
  1270.             from the Admin menu.
  1271.  
  1272.           +o Some printers may clip the output when printing a
  1273.             PostScript version of graph saved by _c_v_s_t_a_t_i_c.
  1274.  
  1275.             Workaround: None, except trying another printer, or
  1276.             re-laying out the graph by hand to avoid clipping.
  1277.  
  1278.        5.5.2  _K_n_o_w_n__P_r_o_b_l_e_m_s__w_i_t_h__M_i_x_e_d__L_a_n_g_u_a_g_e_s
  1279.  
  1280.           +o If you analyze a program that contains both Fortran and
  1281.             C routines, _c_v_s_t_a_t_i_c in scanner mode does not recognize
  1282.             that the C function ffffoooooooo____ and the Fortran function ffffoooooooo
  1283.             refer to the same routine.  In parser mode, _c_v_s_t_a_t_i_c
  1284.             will identify the routines correctly, if it analyzes
  1285.             the C file containing ffffoooooooo____ before the Fortran file that
  1286.             calls ffffoooooooo.  So, make sure that your C files appear
  1287.             earlier in the fileset than your Fortran files.
  1288.  
  1289.  
  1290.  
  1291.  
  1292.  
  1293.  
  1294.  
  1295.  
  1296.  
  1297.  
  1298.  
  1299.  
  1300.  
  1301.  
  1302.  
  1303.  
  1304.  
  1305.  
  1306.  
  1307.  
  1308.  
  1309.  
  1310.  
  1311.  
  1312.  
  1313.  
  1314.  
  1315.  
  1316.  
  1317.  
  1318.  
  1319.  
  1320.  
  1321.  
  1322.  
  1323.  
  1324.                                   - 21 -
  1325.  
  1326.  
  1327.  
  1328.  
  1329.        5.5.3  _G_e_n_e_r_a_l__K_n_o_w_n__P_r_o_b_l_e_m_s__i_n__S_c_a_n_n_e_r__M_o_d_e
  1330.  
  1331.           +o In general, _c_v_s_t_a_t_i_c does not require code to be able
  1332.             to be compiled.  _c_v_s_t_a_t_i_c should provide useful
  1333.             information even when code has syntax errors. However,
  1334.             there are several requirements that must be met for
  1335.             _c_v_s_t_a_t_i_c to work properly. In C and C++, _c_v_s_t_a_t_i_c
  1336.             relies on the existence of matching braces to determine
  1337.             the beginning and ending of blocks and bodies of
  1338.             functions. In Fortran, _c_v_s_t_a_t_i_c relies on the existence
  1339.             of matching end statements. Functions without closing
  1340.             braces, or end statements, or code with too many end
  1341.             statements or mismatched braces can cause unpredictable
  1342.             results. In C, it may be necessary to use _c_v_s_t_a_t_i_c's
  1343.             ----pppprrrreeeepppprrrroooocccceeeessssssss option with heavily _i_f_d_e_f'd code to achieve
  1344.             matched braces.
  1345.  
  1346.             If any of these limitations of scanner mode keeps
  1347.             _c_v_s_t_a_t_i_c from being useful, using parser mode may be
  1348.             the right solution.
  1349.  
  1350.           +o _c_v_s_t_a_t_i_c accepts regular expressions in nearly all
  1351.             fields. This can occasionally cause problems if you
  1352.             unintentionally use a pattern without realizing it is a
  1353.             regular expression. For example, specifying a filename
  1354.             of ffffoooooooo....cccc++++++++ usually fails, because ++++ is a special
  1355.             character in regular expressions.
  1356.  
  1357.             Workaround: Backslash all regular expression special
  1358.             characters when not used to specify a wildcard pattern.
  1359.             For example, the filename mentioned above would be
  1360.             entered as ffffoooooooo....cccc\\\\++++\\\\++++.
  1361.  
  1362.           +o The _c_v_s_t_a_t_i_c Variable query, ``Who Sets'' recognizes
  1363.             only variable assignments that use ``='' to assign
  1364.             directly to a variable.  This query does not recognize
  1365.             or account for aggregate initialization statements in C
  1366.             or C++, references in C++, assignments made as a result
  1367.             of passing or operating on pointers in C, or data,
  1368.             equivalence, common, or assign statements in Fortran.
  1369.  
  1370.             Workaround. Use ``Who References'' to see all locations
  1371.             in which the variable is used and to visually inspect
  1372.             for assignments.
  1373.  
  1374.           +o By default, _c_v_s_t_a_t_i_c does not honor _i_f_d_e_f's in source
  1375.             code. Much of the time, this is desirable behavior.
  1376.             _c_v_s_t_a_t_i_c allows you to find _a_l_l references that satisfy
  1377.             a query. However, this may result in an incorrect or
  1378.             misleading function call tree. Heavily _i_f_d_e_f'd code may
  1379.  
  1380.  
  1381.  
  1382.  
  1383.  
  1384.  
  1385.  
  1386.  
  1387.  
  1388.  
  1389.  
  1390.                                   - 22 -
  1391.  
  1392.  
  1393.  
  1394.             also confuse _c_v_s_t_a_t_i_c, because (in C) _c_v_s_t_a_t_i_c relies
  1395.             on matching braces to detect the end of functions.
  1396.  
  1397.             Workaround: Use the ----pppprrrreeeepppprrrroooocccceeeessssssss flag when starting
  1398.             _c_v_s_t_a_t_i_c. This makes _c_v_s_t_a_t_i_c run much more slowly, but
  1399.             it honors most _i_f_d_e_fs.
  1400.  
  1401.           +o _c_v_s_t_a_t_i_c recognizes many common C, C++, and Fortran
  1402.             language patterns.  However, all three languages allow
  1403.             programmers to write code that is not easily identified
  1404.             by patterns.
  1405.  
  1406.             Workaround: If you find that _c_v_s_t_a_t_i_c misses or
  1407.             misidentifies parts of a program, you can usually
  1408.             resort to string, regular expression, or symbol queries
  1409.             to find the information you are looking for.
  1410.  
  1411.           +o Files containing very long lines are not handled in
  1412.             scanner mode. If a file contains any line longer than
  1413.             3000 characters, _c_v_s_t_a_t_i_c's scanner will fail.
  1414.  
  1415.             Workaround: Use parser mode, or shorten your source
  1416.             lines.
  1417.  
  1418.        5.5.4  _K_n_o_w_n _P_r_o_b_l_e_m_s _U_s_i_n_g _c_v_s_t_a_t_i_c _i_n _S_c_a_n_n_e_r _M_o_d_e _w_i_t_h
  1419.        _C++  _c_v_s_t_a_t_i_c analyzes C++ source code much more accurately
  1420.        in parser mode than in scanner mode.  The following problems
  1421.        are known to occur in scanner mode.  They can be avoided by
  1422.        following the workaround suggestions, or by using parser
  1423.        mode.
  1424.  
  1425.           +o _c_v_s_t_a_t_i_c does not do macro expansion, so classes based
  1426.             on macros used to simulate C++ parameterized types are
  1427.             not detected.
  1428.  
  1429.           +o _c_v_s_t_a_t_i_c does not completely handle function calls made
  1430.             through function pointers, in C or C++. In C++, this
  1431.             includes calls to member functions made through object
  1432.             pointers.  For example, consider the following code
  1433.             segment:
  1434.  
  1435.             ssssaaaammmmpppplllleeeeffffuuuunnnnccccttttiiiioooonnnn (((())))
  1436.             {{{{
  1437.                AAAA ****oooobbbbjjjjeeeecccctttt1111 ==== nnnneeeewwww AAAA(((())));;;;
  1438.                BBBB ****oooobbbbjjjjeeeecccctttt2222 ==== nnnneeeewwww BBBB(((())));;;;
  1439.                oooobbbbjjjjeeeecccctttt1111---->>>>ffffuuuunnnncccc(((())));;;;
  1440.                oooobbbbjjjjeeeecccctttt2222---->>>>ffffuuuunnnncccc(((())));;;;
  1441.             }}}}
  1442.  
  1443.             In this example, _c_v_s_t_a_t_i_c correctly reports that
  1444.             samplefunction() calls func() two times. However, it
  1445.  
  1446.  
  1447.  
  1448.  
  1449.  
  1450.  
  1451.  
  1452.  
  1453.  
  1454.  
  1455.  
  1456.                                   - 23 -
  1457.  
  1458.  
  1459.  
  1460.             cannot determine that these two function calls are
  1461.             actually made to two different member functions,
  1462.             implemented by two different classes. Similarly,
  1463.             _c_v_s_t_a_t_i_c does not know about the _t_h_i_s pointer.
  1464.  
  1465.             Workaround: Don't try to display full function call
  1466.             trees for C++. Instead use queries like ``Who Calls
  1467.             <function>''or ``Who Is Called By <function>'' which
  1468.             produce meaningful results.
  1469.  
  1470.           +o _c_v_s_t_a_t_i_c does not understand overloaded functions.
  1471.  
  1472.             Workaround: Use the text view for all queries involving
  1473.             overloaded functions.
  1474.  
  1475.           +o C++ allows extensive use of operator overloading, which
  1476.             allows you to write code that can obscure what is
  1477.             really happening in the code. Because _c_v_s_t_a_t_i_c is
  1478.             designed around a pattern matcher, novel constructs
  1479.             produced by overloading operators are not normally
  1480.             detected. Constructs that conform to normal language
  1481.             conventions should normally be found. For example, if A
  1482.             and B are objects, and the ``='' operator has been
  1483.             overloaded to indicate an assignment of the contents of
  1484.             object B to the contents of object A, _c_v_s_t_a_t_i_c should
  1485.             be able to handle this situation. However, if some
  1486.             unusual overloading conventions have been used (say,
  1487.             using ``[]'' to mean a function call), _c_v_s_t_a_t_i_c does
  1488.             not show the same results as the C compiler.
  1489.  
  1490.             Workaround: If you have such code, use string or
  1491.             regular expression searches, or symbol searches to find
  1492.             what you are looking for.
  1493.  
  1494.           +o C++ programs containing templates are not well
  1495.             understood by scanner mode.
  1496.  
  1497.             Workaround: Use parser mode.
  1498.  
  1499.        5.5.5  _K_n_o_w_n__p_r_o_b_l_e_m_s__U_s_i_n_g__c_v_s_t_a_t_i_c__w_i_t_h__F_o_r_t_r_a_n
  1500.  
  1501.           +o Problem: cvstatic changes case in source files.
  1502.  
  1503.             Workaround:  For best results, ignore case:
  1504.  
  1505.             Because the Fortran compilers translate Fortran
  1506.             programs to lower (for Fortran 77) or upper (for
  1507.             Fortran 90) case when analyzing them, you may have
  1508.             trouble selecting a symbol name from the Source View
  1509.             and then using the selection as the target of a query.
  1510.             Therefore, when using the Static Analyzer on Fortran
  1511.  
  1512.  
  1513.  
  1514.  
  1515.  
  1516.  
  1517.  
  1518.  
  1519.  
  1520.  
  1521.  
  1522.                                   - 24 -
  1523.  
  1524.  
  1525.  
  1526.             sources, it is best to select the Ignore Case option,
  1527.             either through the General Option menu, or persistently
  1528.             through the use of the X resource mechanism thus:
  1529.  
  1530.                     cvstatic*ignoreCase: True
  1531.  
  1532.           +o Problem: Fortran file suffixes are ambiguous.
  1533.  
  1534.             Workaround: Tell cvstatic what suffixes you use for
  1535.             which Fortran variant.
  1536.  
  1537.             Both Fortran 77 and Fortran 90 accept files with the
  1538.             the suffixes .f and .F.  So, there is no obvious way
  1539.             for the Static Analyzer to tell whether a source file
  1540.             is Fortran 77 or Fortran 90.
  1541.  
  1542.             To indicate that you want a particular suffix to
  1543.             correspond to a particular language, you can set the
  1544.             suffixSource X resource before running cvstatic.  For
  1545.             example:
  1546.  
  1547.             *suffixSource: C++.c++ C++.C C++.cxx C++.h C.c
  1548.             Fortran.f Fortran90.F Fortran90.f90
  1549.  
  1550.             This line in your .Xdefaults file indicates that you
  1551.             want files ending .f to be analyzed as Fortran 77
  1552.             codes, while files ending .F or .f90 are Fortran 90.
  1553.  
  1554.             You may want to analyze a set of files in which some
  1555.             files ending .f are Fortran 77 while other files with
  1556.             the same suffix are Fortran 90.  If so, the only way to
  1557.             distinguish them is for you manually to edit the
  1558.             cvstatic.fileset file and make sure that each filename
  1559.             is followed by the correct driver.  For example, these
  1560.             two lines in the fileset file indicate that foo.f is a
  1561.             Fortran 77 file, while bar.f is Fortran 90:
  1562.  
  1563.                 ////uuuussssrrrr////ppppeeeeoooopppplllleeee////yyyyoooouuuu////ffffoooooooo....ffff ffff77777777
  1564.                 ////uuuussssrrrr////ppppeeeeoooopppplllleeee////yyyyoooouuuu////bbbbaaaarrrr....ffff ffff99990000
  1565.  
  1566.        _c_v_s_t_a_t_i_c analyzes Fortran source code much more accurately
  1567.        in parser mode than in scanner mode.  The following problems
  1568.        are known to occur in scanner mode.  They can be avoided by
  1569.        following the workaround suggestions, or by using parser
  1570.        mode.
  1571.  
  1572.           +o _c_v_s_t_a_t_i_c occasionally misses function calls and other
  1573.             statements that directly follow an _i_f statement on the
  1574.             same line.
  1575.  
  1576.  
  1577.  
  1578.  
  1579.  
  1580.  
  1581.  
  1582.  
  1583.  
  1584.  
  1585.  
  1586.  
  1587.  
  1588.                                   - 25 -
  1589.  
  1590.  
  1591.  
  1592.           +o _c_v_s_t_a_t_i_c uses a pattern matching approach. This
  1593.             approach does not allow the tool to detect the
  1594.             irregular use of spaces within Fortran symbols, even
  1595.             though these are allowed by the Fortran compiler. For
  1596.             example, the Fortran compiler accepts the statement:
  1597.  
  1598.                    ssssuuuubbbb rrrroooouuuuttttiiiinnnneeee mmmmyyyy
  1599.                   1111ffffuuuunnnncccc ttttiiiioooonnnn
  1600.  
  1601.             as if it were written:
  1602.  
  1603.                   ssssuuuubbbbrrrroooouuuuttttiiiinnnneeee mmmmyyyyffffuuuunnnnccccttttiiiioooonnnn
  1604.  
  1605.             _c_v_s_t_a_t_i_c does not handle such conventions.
  1606.  
  1607.             Workaround: None in scanner mode. Silicon Graphics
  1608.             strongly suggests changing such code to use a more
  1609.             readable coding style.
  1610.  
  1611.           +o _c_v_s_t_a_t_i_c does not support the use of Fortran keywords
  1612.             for uses other than their intrinsic function. For
  1613.             example, _c_v_s_t_a_t_i_c always recognizes word ``if'' as
  1614.             starting a conditional statement. Programs that use
  1615.             ``if'' as a variable or function name are not analyzed
  1616.             correctly.
  1617.  
  1618.             Workaround: None in scanner mode. Silicon Graphics
  1619.             strongly suggests changing such code to use a more
  1620.             readable coding style.
  1621.  
  1622.           +o In some situations, _c_v_s_t_a_t_i_c can mistake references to
  1623.             arrays as function calls. This is particularly true
  1624.             when the Fortran code relies on include files to
  1625.             declare arrays, common blocks, and so on. _c_v_s_t_a_t_i_c does
  1626.             not analyze header files at the point at which they
  1627.             occur, but simply adds them to the list of files to be
  1628.             analyzed. This contributes greatly to the speed of
  1629.             _c_v_s_t_a_t_i_c, but means that _c_v_s_t_a_t_i_c does not have various
  1630.             type declarations available to it. Because Fortran
  1631.             arrays cannot be differentiated from function calls
  1632.             without a declaration, _c_v_s_t_a_t_i_c identifies arrays not
  1633.             defined in the file in which they are referenced as
  1634.             function calls.
  1635.  
  1636.             Workaround: Use the Results Filter to exclude
  1637.             ``external'' functions. This limits all queries to
  1638.             those functions actually defined in the fileset.
  1639.             Excluding external functions hides all array references
  1640.             erroneously identified as function calls, but also
  1641.             hides all calls to library functions, intrinsic
  1642.             functions, or other routines declared outside the
  1643.  
  1644.  
  1645.  
  1646.  
  1647.  
  1648.  
  1649.  
  1650.  
  1651.  
  1652.  
  1653.  
  1654.                                   - 26 -
  1655.  
  1656.  
  1657.  
  1658.             fileset.
  1659.  
  1660.        5.5.6  _K_n_o_w_n__P_r_o_b_l_e_m_s__U_s_i_n_g__c_v_s_t_a_t_i_c__i_n__P_a_r_s_e_r__M_o_d_e
  1661.             Sometimes the General query "Where Symbol Used" fails
  1662.             to report some call sites, if the target of the query
  1663.             was a function.
  1664.  
  1665.             WorkAround: Use the Function query "Who Calls" or
  1666.             "Where Function Used" to get a complete list of places
  1667.             wehre the target function is called or otherwise used.
  1668.  
  1669.           +o The query Where Type Used may return duplicate results
  1670.             in C and C++ programs.  For example, asking Where Type
  1671.             Used Foo will produce two copies of the result showing
  1672.             the definition of the symbol
  1673.  
  1674.                        FFFFoooooooo ffff;;;;
  1675.  
  1676.             If one of these locations is shown without a function
  1677.             field and one is shown with a function, the latter is
  1678.             correct.
  1679.  
  1680.             Workaround: If you are explicitly looking for
  1681.             definitions, use the queries List Data of Type or List
  1682.             Functions of Type instead.  Otherwise, just ignore the
  1683.             duplications.
  1684.  
  1685.           +o The query Where Type Used is confusing about pointers
  1686.             in C and C++.
  1687.  
  1688.             If you ask Where Type Used about a user-defined type
  1689.             named Foo, the query will display all uses of Foo,
  1690.             including uses of types like Foo*, Foo**, Foo[], etc.
  1691.  
  1692.             But if you ask Where Type Used about a built-in type
  1693.             like void or char, the query will display only uses of
  1694.             that exact type.
  1695.  
  1696.             Workaround: Query explicitly about typenames like
  1697.             void*, char**, etc, that contain no user-defined
  1698.             typenames.
  1699.  
  1700.           +o Queries on "integer" and "real" in fortran don't work.
  1701.  
  1702.             Fortran reports integer types as having typenames I*4
  1703.             and I*8, real types with typenames R*4, R*8, complex
  1704.             types with typenames CM*8 and CM*16, and logical types
  1705.             as L*4.
  1706.  
  1707.             Workaround: To inquire about uses and declarations with
  1708.             these types, enter I*4 (or whatever) into the target
  1709.  
  1710.  
  1711.  
  1712.  
  1713.  
  1714.  
  1715.  
  1716.  
  1717.  
  1718.  
  1719.  
  1720.                                   - 27 -
  1721.  
  1722.  
  1723.  
  1724.             field instead of "integer".
  1725.  
  1726.           +o Mismatched member function declarations and definitions
  1727.             are not recognized by _c_v_s_t_a_t_i_c'_s parser.  The parser
  1728.             runs into trouble processing a member function if the
  1729.             signature of its declaration and definition are not
  1730.             identical.  For example, if the code contains something
  1731.             like this:
  1732.  
  1733.             ttttyyyyppppeeeeddddeeeeffff iiiinnnntttt**** iiiinnnnttttppppttttrrrr;;;;
  1734.  
  1735.             ccccllllaaaassssssss AAAA {{{{
  1736.             ppppuuuubbbblllliiiicccc::::
  1737.                 AAAA ((((iiiinnnntttt **** iiii))));;;;
  1738.             }}}};;;;
  1739.  
  1740.             AAAA::::::::AAAA ((((iiiinnnnttttppppttttrrrr iiii)))) {{{{
  1741.             }}}}
  1742.  
  1743.             the parser will print the error message "no record for
  1744.             method A::A?" and terminate processing of the file.
  1745.  
  1746.             Workaround: analyze code like this in scanner mode, or
  1747.             change the type signatures so that the definition and
  1748.             declaration match.
  1749.  
  1750.           +o _c_v_s_t_a_t_i_c's parser mode is better at building a new
  1751.             database than at modifying an existing one.  If you
  1752.             build a parser-mode database and then change a file and
  1753.             reparse it, the database will grow each time you rescan
  1754.             the file.  Not all space is reclaimed.  Additional arcs
  1755.             may appear in the Call Tree view representing defunct
  1756.             call site information.
  1757.  
  1758.             Workaround: After a few files are modified and re-
  1759.             analyzed, it is best to use Force Scan to rebuild the
  1760.             entire parser-mode database. For a large code base that
  1761.             is slow to parse, you can use the -batch flag to
  1762.             rebuild the database overnight.
  1763.  
  1764.           +o Functions generated by templates are recognized and
  1765.             displayed by _c_v_s_t_a_t_i_c, but it treats them as external
  1766.             functions:  functions that are declared or used within
  1767.             the fileset but are not defined there. Consequently,
  1768.             they do not appear in the results of the ``Query List
  1769.             All Functions''.
  1770.  
  1771.             Workaround: Use specific queries about these functions,
  1772.             like ``Where Function Called'', or add them manually to
  1773.             Call Tree graphs.
  1774.  
  1775.  
  1776.  
  1777.  
  1778.  
  1779.  
  1780.  
  1781.  
  1782.  
  1783.  
  1784.  
  1785.  
  1786.                                   - 28 -
  1787.  
  1788.  
  1789.  
  1790.           +o The function "main" appears in the list of Functions
  1791.             Not Called, if it is not called explicitly from the
  1792.             source code.  ("main" is rarely called explicitly.)
  1793.  
  1794.             Workaround: You can add the function "main" manually to
  1795.             any graphical display of functions.
  1796.  
  1797.           +o Graphical display of a single member function called
  1798.             through derived classes is incomplete.  If a C++ member
  1799.             function FFFFoooooooo::::::::FFFFuuuunnnncccc is called through classes derived
  1800.             from the ccccllllaaaassssssss FFFFoooooooo, each derived function FFFFuuuunnnncccc will
  1801.             appear as a separate function in the Text View list of
  1802.             functions.  However, only one node will appear for FFFFuuuunnnncccc
  1803.             in the Call Tree View.
  1804.  
  1805.             Workaround: To see the full list of definitions and
  1806.             calls of FFFFuuuunnnncccc, use Text Mode.  If you double click on
  1807.             the definition of one of the derived FFFFuuuunnnnccccs, you will
  1808.             navigate either to the definition of the function (if
  1809.             you click on the version in FFFFoooooooo), or to the definition
  1810.             of the derived class through which FFFFuuuunnnncccc was called.
  1811.  
  1812.           +o If you are analyzing C++ code in which multiple non-
  1813.             member functions have the same name, _c_v_s_t_a_t_i_c will
  1814.             think they are all the same function with one
  1815.             definition and several declarations.
  1816.  
  1817.             Workaround: You can get to the definitions by using the
  1818.             ``Where Defined'' and ``Where Declared'' queries on
  1819.             functions.
  1820.  
  1821.           +o When you first bring up _c_v_s_t_a_t_i_c, if you switch the
  1822.             view from Text View to a graph view before building the
  1823.             parser database and doing your first query, the graph
  1824.             may incorrectly display as empty.
  1825.  
  1826.             Workaround:  Stay in Text View to perform your first
  1827.             query, and then switch to whichever graph view you
  1828.             wish.  Or, if you have already brought up _c_v_s_t_a_t_i_c in a
  1829.             graph view and built the database, hit ``Rescan'' in
  1830.             the Admin menu, and then redo your query.
  1831.  
  1832.  
  1833.        5.6  _W_o_r_k_S_h_o_p__C_+_+__B_r_o_w_s_e_r
  1834.  
  1835.           +o The _C++ _B_r_o_w_s_e_r currently works only on files in the
  1836.             parser fileset.  So if you have a fileset which has
  1837.             only files in the scanner fileset, the browser will not
  1838.             work. To generate the database, you have to put files
  1839.             in the parser fileset and issue a rebuild in _c_v_s_t_a_t_i_c.
  1840.             Once the database is created you can use Browser to
  1841.  
  1842.  
  1843.  
  1844.  
  1845.  
  1846.  
  1847.  
  1848.  
  1849.  
  1850.  
  1851.  
  1852.                                   - 29 -
  1853.  
  1854.  
  1855.  
  1856.             examine the C++ classes.
  1857.  
  1858.           +o When using the C++ Browser, if you make changes to the
  1859.             code in the files that are present in the fileset, the
  1860.             changes will not be reflected in the information
  1861.             presented by the C++ Browser until you issue a Rescan
  1862.             command in _c_v_s_t_a_t_i_c, as follows:
  1863.  
  1864.             *    Make your changes.
  1865.  
  1866.             *    Exit the C++ Browser (but not cvstatic).
  1867.  
  1868.             *    Issue a FFFFoooorrrrcccceeee SSSSccccaaaannnn from the cvstatic AAAAddddmmmmiiiinnnn menu.
  1869.  
  1870.             *    Restart the browser by selecting AAAAddddmmmmiiiinnnn/CCCC++++++++ BBBBrrrroooowwwwsssseeeerrrr
  1871.                  menu in cvstatic.
  1872.  
  1873.             Incident 186990.
  1874.  
  1875.           +o Duplicate class definitions encountered in your files
  1876.             in the parser fileset will end up as a single class
  1877.             with accumulating members from both the definitions.
  1878.             This happens when the file defining the class is
  1879.             included from two different paths or there are two
  1880.             genuine class definitions for the same class name in
  1881.             your fileset.
  1882.  
  1883.             Incident 206922.
  1884.  
  1885.           +o If you use typedefs, and use it to give alternate names
  1886.             to classes (as in _t_y_p_e_d_e_f _c_l_a_s_s _A _B;) - you may that
  1887.             the Build Window shows some warnings about not finding
  1888.             the class B and that the information collected about
  1889.             the usage of class A will be missing many of the
  1890.             references through its typedef B.
  1891.  
  1892.             This kind of typedef is more commonly found in template
  1893.             code. There is no good workaround currently, other than
  1894.             not using the typedef in question.
  1895.  
  1896.             Incident 217830.
  1897.  
  1898.           +o If you use typedefs, and use it inconsistently in
  1899.             declaring and defining class members (as in the
  1900.             following example), you will find that information
  1901.             regarding those members is either missing or faulty.
  1902.             The workaround is to use the same prototype at the
  1903.             point of definition as at the point of declaration.
  1904.  
  1905.                 ttttyyyyppppeeeeddddeeeeffff iiiinnnntttt IIIINNNNTTTT;;;;
  1906.                 ccccllllaaaassssssss AAAA {{{{
  1907.  
  1908.  
  1909.  
  1910.  
  1911.  
  1912.  
  1913.  
  1914.  
  1915.  
  1916.  
  1917.  
  1918.                                   - 30 -
  1919.  
  1920.  
  1921.  
  1922.                    vvvvooooiiiidddd ffffoooooooo ((((IIIINNNNTTTT))));;;;
  1923.                 }}}};;;;
  1924.  
  1925.                 vvvvooooiiiidddd AAAA::::::::ffffoooooooo ((((iiiinnnntttt vvvvaaaallll)))) ............   //////// ggggeeeettttssss wwwwaaaarrrrnnnniiiinnnngggg,,,, aaaannnndddd iiiissss mmmmiiiissssssssiiiinnnngggg
  1926.                                             //////// ffffrrrroooommmm ssssttttaaaattttiiiicccc aaaannnnaaaallllyyyyssssiiiissss iiiinnnnffffoooo....
  1927.  
  1928.             Incident 184455.
  1929.  
  1930.           +o Usage information for template classes is managed only
  1931.             on a per-instantiation basis.  If you use templates in
  1932.             your code, then each instantiation, and the template
  1933.             itself, will show up as classes in the C++ Browser.
  1934.  
  1935.             For instance, if you have a template class Foo<T>, then
  1936.             there will be a class called FOO<T> and classes FOO<A>,
  1937.             FOO<B> etc., for the template definition prototype of
  1938.             FOO and its instantiations with A, B, etc.,
  1939.             respectively. And the usage information on FOO<T>
  1940.             currently shown is not the amalgamation of usage
  1941.             information on its instantiations FOO<A>, FOO<B>, etc.
  1942.  
  1943.           +o Be careful about overwriting man pages which are
  1944.             generated using the automatic class man page generation
  1945.             facility.
  1946.  
  1947.             When you generate a manpage for a class, through the
  1948.             C++ browser, you get a skeleton, in which you have to
  1949.             fill in all the descriptions. Please remember that if
  1950.             you change the class and generate a new man page for
  1951.             that class again, your changes to the file will be lost
  1952.             if you ignore the man page overwrite warning dialog.
  1953.  
  1954.             To avoid losing your changes to a manpage file
  1955.             generated by C++ Browser do the following:
  1956.  
  1957.             *    Move the existing manpage out of the way to some
  1958.                  other file.
  1959.  
  1960.             *    Generate the new (skeleton) man page.
  1961.  
  1962.             *    Merge the changes from the saved file to the new
  1963.                  man page generated by the C++ Browser.
  1964.  
  1965.           +o When you use an application which allocates lot of
  1966.             colors in the default color map and then use cvstatic
  1967.             or C++ browser to bring up graphs, you might get all
  1968.             black nodes with un-readable text. The only known
  1969.             workaround to this problem is to kill the X server and
  1970.             login again. Be sure that you bring up cvstatic before
  1971.             you bring up the offending application. This problem
  1972.             has been seen with viewing books which have full color
  1973.  
  1974.  
  1975.  
  1976.  
  1977.  
  1978.  
  1979.  
  1980.  
  1981.  
  1982.  
  1983.  
  1984.                                   - 31 -
  1985.  
  1986.  
  1987.  
  1988.             pictures.
  1989.  
  1990.  
  1991.        5.7  _W_o_r_k_S_h_o_p__P_e_r_f_o_r_m_a_n_c_e__A_n_a_l_y_z_e_r
  1992.  
  1993.           +o Total-time and bottleneck experiments will overcount
  1994.             inclusive time for recursive functions (Incident
  1995.             #438591)
  1996.  
  1997.           +o The Main View has a notion of a default trap that is a
  1998.             stop trap if data collection has not been enabled in
  1999.             the Performance Panel (where ``enabled'' means after
  2000.             _A_c_c_e_p_t or _O_K was clicked), and a sample trap if it has
  2001.             been enabled.  This setting is independent of the
  2002.             default trap set in the Trap Manager.  Clicking in the
  2003.             margin of the MainView source window sets or clears the
  2004.             MainView default trap, and does not affect a trap of
  2005.             the other type.
  2006.  
  2007.           +o The WorkShop Performance Analyzer can record
  2008.             experiments on MP FORTRAN programs, but there are a
  2009.             number of anomalies in the displayed data that require
  2010.             explanation.  For all FORTRAN MP compilations, parallel
  2011.             loops within the program are represented as subroutines
  2012.             with names relating to the source routine in which they
  2013.             are embedded.  The naming conventions for these
  2014.             subroutines are different for o32-bit, N32, and 64-bit
  2015.             compilations.  In the linpack benchmark, most of the
  2016.             time spent is in the source routine _D_A_X_P_Y, which can be
  2017.             parallelized.  The MP loop-body routines are invoked
  2018.             indirectly from the original function, and will show up
  2019.             as directly calls from a routine name __mp_parallel_do.
  2020.  
  2021.             When compiled with the 7.2 or later compilers, in
  2022.             either 64-bits, or n32, the MP loop-body routine is
  2023.             named "__mpdo_daxpy_1", and the function is named
  2024.             "daxpy_".  However, there is a test in the compiled
  2025.             loop to determine if the work to be done is sufficient
  2026.             to be worth running in parallel.  That means if the
  2027.             test succeeds, time will be shown in the routine
  2028.             __mpdo_daxpy_1, while if the test fails, the time will
  2029.             be recorded in the routine daxpy_.
  2030.  
  2031.             In an o32-bit version, the _D_A_X_P_Y routine is named
  2032.             "daxpy_", and the MP loop body routine
  2033.             "_daxpy_519_aaab_".
  2034.  
  2035.             In all three cases, for an ideal time experiment on a
  2036.             uniprocessor -_g run,the inclusive and exclusive
  2037.             function level times are correct.  The source
  2038.             annotations, however, behave differently in most cases.
  2039.  
  2040.  
  2041.  
  2042.  
  2043.  
  2044.  
  2045.  
  2046.  
  2047.  
  2048.  
  2049.  
  2050.                                   - 32 -
  2051.  
  2052.  
  2053.  
  2054.             With the 7.2 or 6.x compilers, source annotations for
  2055.             the exclusive time are correctly shown for each line,
  2056.             but the inclusive time for the first line of the loop
  2057.             (_d_o statement) includes the time spent in the loop
  2058.             body. This same time appears on the lines comprising
  2059.             the loop's body, in effect, representing a double-
  2060.             counting.  When used in conjunction with WorkShop Pro
  2061.             MPF's Parallel Analyzer View, the loop performance data
  2062.             will incorrectly also reflect the double counting, and
  2063.             the time will not be always shown as a percentage:
  2064.             whenever it would exceed 100%, it is shown as <_n/_a>.
  2065.             The numerical time value shown reflects the double
  2066.             counting.
  2067.  
  2068.             In 32-bit source annotations, the exclusive time is
  2069.             incorrectly shown for the line comprising the loop's
  2070.             body, as the line-level data for the loop-body routine
  2071.             ("_daxpy_519_aaab_") does not refer to proper lines.
  2072.             If the program was compiled with the -_m_p__k_e_e_p flag, the
  2073.             line-level data should refer to the temporary files
  2074.             that are saved from the compilation, but the temporary
  2075.             files do not contain that information, so no source or
  2076.             disassembly data can be shown.  The disassembly data
  2077.             for the main routine does not show the times for the
  2078.             loop-body.
  2079.  
  2080.             If the 32-bit program was compiled without -_m_p__k_e_e_p,
  2081.             the line-level data for the loop-body routine is
  2082.             incorrect, with most lines referred to line 0 of the
  2083.             file, and the rest to other lines at seemingly random
  2084.             places in the file.  Consequently, spurious annotations
  2085.             will appear on these other lines.  Disassembly
  2086.             correctly shows the instructions, and their data, but
  2087.             the line numbers shown are wrong.  MPF's Parallel
  2088.             Analyzer correctly shows the loop data in most cases,
  2089.             but the same incorrect line numbers can cause data
  2090.             relating to one loop to show up in other parts of the
  2091.             program.  This reflects what is essentially the same
  2092.             double-counting problem as seen in 64-bits, but the
  2093.             extra counts go to other places in the file, rather
  2094.             than the first line of the loop.
  2095.  
  2096.             NNNNOOOOTTTTEEEE:::: We recommend against using the -_m_p__k_e_e_p flag.
  2097.  
  2098.           +o For MP experiments run under the debugger, stopping one
  2099.             thread can cause the notion of time in other threads to
  2100.             get confused.  It is not recommended.
  2101.  
  2102.           +o The inclusive data shown in _c_v_p_e_r_f represents the
  2103.             instruction counts and/or PC sampling data summed over
  2104.             the routine and those routines that it calls.  The
  2105.  
  2106.  
  2107.  
  2108.  
  2109.  
  2110.  
  2111.  
  2112.  
  2113.  
  2114.  
  2115.  
  2116.                                   - 33 -
  2117.  
  2118.  
  2119.  
  2120.             computations are based on a heuristic that assumes that
  2121.             all calls from all callers are equivalent.  For
  2122.             programs where this heuristic is not applicable, for
  2123.             example, where one call to a matrix-multiply routine is
  2124.             for matrices of order four, while a second call is for
  2125.             matrices of order 100, the cumulative data may be
  2126.             misleading.
  2127.  
  2128.           +o Line-level data assigns a value to a line equal to the
  2129.             highest value for any instructions attributed to that
  2130.             line.  It can be confusing, because compiler
  2131.             optimizations often rearrange the code in ways that is
  2132.             non-obvious.  Looking at a disassembly view of the data
  2133.             can help.
  2134.  
  2135.           +o Line-level data from assembler routines can be
  2136.             misleading.  The symbol table often has instructions
  2137.             attributed to the wrong source line.
  2138.  
  2139.           +o _c_v_p_e_r_f filters out nodes and arcs that were not
  2140.             executed during the current caliper setting.  This
  2141.             feature can lead to confusing displays, where nodes
  2142.             that are known to be in the program do not appear.
  2143.  
  2144.             Workaround: The Preferences menu can be used to disable
  2145.             the filtering.
  2146.  
  2147.           +o _c_v_p_e_r_f does not support live performance experiments.
  2148.             That is, you should not bring up _c_v_p_e_r_f until the
  2149.             experiment is over.  If you do, it will not update as
  2150.             more data is recorded.
  2151.  
  2152.           +o Performance experiments on multi-process applications
  2153.             can occasionally be unreliable if sample events are
  2154.             quickly preceded by process creation, or succeeded by
  2155.             process termination.
  2156.  
  2157.           +o Heap View scrolls poorly and blocks flash on large
  2158.             experiments.  Its functionality has been mostly
  2159.             subsumed by Leak View, Malloc View, and Malloc Error
  2160.             View.  (Incident# 571496)
  2161.  
  2162.           +o Source or disassembly cycle annotations may overflow
  2163.             for high counts in pixie mode.  (Incident# 244871)
  2164.  
  2165.           +o Cvperf can not generate source annotations for corded
  2166.             binaries.  (Incident# 597302)
  2167.  
  2168.           +o Cvperf option for noise-filter w/"important children"
  2169.             command may not work.  (Incident# 503751)
  2170.  
  2171.  
  2172.  
  2173.  
  2174.  
  2175.  
  2176.  
  2177.  
  2178.  
  2179.  
  2180.  
  2181.  
  2182.                                   - 34 -
  2183.  
  2184.  
  2185.  
  2186.           +o Cvperf's call graph will be incomplete for the Fortran
  2187.             symbol "MAIN__" and the program name if produced by 7.2
  2188.             or later compilers.  (Incident# 503928)
  2189.  
  2190.           +o Experiment file aggregation by cvperf is limited to
  2191.             files from a single run.  Aggregation is also limited
  2192.             to experiment files that have the same number of
  2193.             caliper points.  (Incident #618507)
  2194.  
  2195.           +o When running performance experiments on MPI
  2196.             applications, a master experiment file will get
  2197.             generated on each host in addition to the experiment
  2198.             files for the MPI slaves. The master experiment file
  2199.             contains no application-related performance data.
  2200.  
  2201.           +o Call stacks with the "cc" marching order can not be
  2202.             generated for trap-based caliper points.  (Incident
  2203.             #618550)
  2204.  
  2205.           +o Performance data collection doesn't imply attachment to
  2206.             the debugger anymore.  If that's required (for trap-
  2207.             based caliper points for example), then it can be set
  2208.             to do so via the configuration option of the Perf menu.
  2209.  
  2210.  
  2211.        5.8  _W_o_r_k_S_h_o_p__T_e_s_t_e_r
  2212.  
  2213.        5.8.1  _W_o_r_k_S_h_o_p__T_e_s_t_e_r__L_i_m_i_t_a_t_i_o_n_s
  2214.  
  2215.           +o Instrumented programs can increase in size by a factor
  2216.             of 2X to 5X.  However, DSO caching and sharing
  2217.             alleviates this problem greatly.
  2218.  
  2219.           +o Block and branch coverage are at the assembly language
  2220.             level.  They can provide useful metrics and do map back
  2221.             to the source lines.  Note that several assembly branch
  2222.             instructions may map back to the same source line.  To
  2223.             see the C, C++, and Fortran source level blocks and
  2224.             branches, use _c_v_c_o_v _l_s_s_o_u_r_c_e.
  2225.  
  2226.           +o Compilation with the debug flag -_g builds assembly
  2227.             language branches and blocks that can never be
  2228.             executed.  This adversely affects overall coverage.  By
  2229.             compiling with "O1" (the default), some of the unused
  2230.             assembly branches and blocks are not built.  This gives
  2231.             a more accurate block and branch coverage metric.
  2232.             Function and arc coverage are unaffected by compile
  2233.             flags.
  2234.  
  2235.           +o C++ in-line functions are not counted as functions
  2236.             unless they are out-of-lined by the compiler.
  2237.  
  2238.  
  2239.  
  2240.  
  2241.  
  2242.  
  2243.  
  2244.  
  2245.  
  2246.  
  2247.  
  2248.                                   - 35 -
  2249.  
  2250.  
  2251.  
  2252.           +o By default, arguments of functions are not displayed in
  2253.             query results.  This can be confusing for C++
  2254.             overloaded functions because there is no way to
  2255.             distinguish between them.  To work around this problem,
  2256.             use the -_a_r_g option to show full function signatures.
  2257.  
  2258.           +o The default size of the SourceView annotation canvas
  2259.             may not be large enough to hold very large counts.  The
  2260.             resource name for setting canvas width for SourceView
  2261.             is "canvasWidth".  The default value is 60.  The user
  2262.             can modify this width by modifying the following
  2263.             resource found in the Cvxcov app-defaults file,
  2264.             "Cvxcov*test*testData*canvasWidth".
  2265.  
  2266.           +o _T_e_s_t_e_r currently uses object level instrumentation.
  2267.             This has several advantages:
  2268.  
  2269.                 ((((1111)))) CCCCoooovvvveeeerrrraaaaggggeeee ddddaaaattttaaaa ccccaaaannnn bbbbeeee oooobbbbttttaaaaiiiinnnneeeedddd wwwwiiiitttthhhhoooouuuutttt aaaacccccccceeeessssssss ttttoooo tttthhhheeee
  2270.                     ssssoooouuuurrrrcccceeee ccccooooddddeeee....
  2271.                 ((((2222)))) CCCCoooovvvveeeerrrraaaaggggeeee ddddaaaattttaaaa ccccaaaannnn bbbbeeee oooobbbbttttaaaaiiiinnnneeeedddd wwwwiiiitttthhhhoooouuuutttt rrrreeeeccccoooommmmppppiiiillllaaaattttiiiioooonnnn////rrrreeeebbbbuuuuiiiilllldddd....
  2272.                 ((((3333)))) TTTThhhhiiiissss ssssuuuuppppppppoooorrrrttttssss CCCC,,,, CCCC++++++++,,,, aaaannnndddd FFFFoooorrrrttttrrrraaaannnn wwwwiiiitttthhhhoooouuuutttt ssssppppeeeecccciiiiaaaallll
  2273.                     llllaaaannnngggguuuuaaaaggggeeee ssssuuuuppppppppoooorrrrtttt ffffrrrroooommmm tttthhhheeee ccccoooommmmppppiiiilllleeeerrrrssss....
  2274.  
  2275.             This has several disadvantages:
  2276.  
  2277.                 ((((1111)))) BBBBlllloooocccckkkk aaaannnndddd bbbbrrrraaaannnncccchhhh ccccoooouuuunnnnttttssss aaaarrrreeee aaaatttt tttthhhheeee aaaasssssssseeeemmmmbbbbllllyyyy llllaaaannnngggguuuuaaaaggggeeee lllleeeevvvveeeellll....
  2278.                 ((((2222)))) MMMMoooorrrreeee ddddeeeettttaaaaiiiilllleeeedddd ccccoooovvvveeeerrrraaaaggggeeee rrrreeeeqqqquuuuiiiirrrreeeessss kkkknnnnoooowwwwlllleeeeddddggggeeee ooooffff tttthhhheeee
  2279.                     llllaaaannnngggguuuuaaaaggggeeee sssseeeemmmmaaaannnnttttiiiiccccssss.... FFFFoooorrrr eeeexxxxaaaammmmpppplllleeee,,,, hhhhaaaassss eeeevvvveeeerrrryyyy ppppoooossssssssiiiibbbblllleeee ccccaaaasssseeee
  2280.                     iiiinnnn aaaa mmmmuuuullllttttiiiipppplllleeee ccccoooonnnnddddiiiittttiiiioooonnnnaaaallll ffffiiiirrrreeeedddd dddduuuurrrriiiinnnngggg tttteeeessssttttiiiinnnngggg....
  2281.  
  2282.           +o _W_e_a_k _e_x_t_e_r_n_a_l_s refer to an aliasing facility used by
  2283.             the compilation environment.  For example, while user
  2284.             programs may call the function "read", the actual
  2285.             function name in the C library that implements "read"
  2286.             is "_read". In this case, "read" is a weak external for
  2287.             "_read".  If the user CONSTRAINS coverage on either
  2288.             name, _T_e_s_t_e_r will report the results correctly.
  2289.             However, _T_e_s_t_e_r will choose the name used to implement
  2290.             the function, in this case "_read".
  2291.  
  2292.           +o -_f_u_n_c__p_a_t_t_e_r_n is a function pattern used in the
  2293.             following _c_v_c_o_v subcommands: _l_s_b_l_o_c_k, _l_s_b_r_a_n_c_h, _l_s_f_u_n,
  2294.             _l_s_t_r_a_c_e.  Currently, only the following "patterns" are
  2295.             matched.
  2296.  
  2297.                 """"DDDDSSSSOOOO::::****""""              -------- aaaallllllll ffffuuuunnnnccccttttiiiioooonnnnssss iiiinnnn aaaa DDDDSSSSOOOO
  2298.                 DDDDSSSSOOOO::::ffffuuuunnnnccccttttiiiioooonnnn____nnnnaaaammmmeeee    -------- ssssppppeeeecccciiiiffffiiiicccc ffffuuuunnnnccccttttiiiioooonnnn iiiinnnn aaaa DDDDSSSSOOOO
  2299.                 ffffuuuunnnnccccttttiiiioooonnnn____nnnnaaaammmmeeee        -------- ffffuuuunnnnccccttttiiiioooonnnn____nnnnaaaammmmeeee iiiinnnn mmmmaaaaiiiinnnn pppprrrrooooggggrrrraaaammmm aaaannnndddd ddddssssoooo''''ssss
  2300.                 <<<< ooooppppttttiiiioooonnnn nnnnooootttt uuuusssseeeedddd >>>>  -------- aaaallllllll ffffuuuunnnnccccttttiiiioooonnnnssss aaaarrrreeee iiiinnnncccclllluuuuddddeeeedddd iiiinnnn qqqquuuueeeerrrryyyy
  2301.  
  2302.  
  2303.  
  2304.  
  2305.  
  2306.  
  2307.  
  2308.  
  2309.  
  2310.  
  2311.  
  2312.  
  2313.  
  2314.                                   - 36 -
  2315.  
  2316.  
  2317.  
  2318.           +o Sharing of the WorkShop Performance Analyzer
  2319.             performance experiment data is supported in _c_v_c_o_v but
  2320.             not in _c_v_x_c_o_v of this release.
  2321.  
  2322.           +o Output of query results to a printer is not supported
  2323.             in this release.  As a workaround, the user can save
  2324.             query results to a file, and then send that file to a
  2325.             printer.
  2326.  
  2327.           +o Experiment data for test sets/test groups cannot be
  2328.             moved/copied (mv, cp) without invalidating the data.
  2329.             Leaf tests can be moved/copied.
  2330.  
  2331.           +o Both the _l_s_t_r_a_c_e feature (argument tracing) and the
  2332.             _l_s_s_o_u_r_c_e feature (mapping block counts to actual
  2333.             source) require the code to be compiled with -_g.  A
  2334.             notable exception to this is return value tracing which
  2335.             can trace the return value on functions that are not
  2336.             compiled with -_g (e.g., _l_i_b_c functions).
  2337.  
  2338.           +o _c_v_c_o_v requires that all instrumentation be performed
  2339.             before the experiment is run. This includes
  2340.             instrumentation for programs that are forked/exec'ed or
  2341.             sproc'ed.  _c_v_m_o_n is the program used by _c_v_c_o_v to
  2342.             monitor the experiment.  If _c_v_m_o_n encounters child
  2343.             processes, and the coverage experiment includes any
  2344.             executables other than the main program, then _c_v_m_o_n
  2345.             will instrument the executables for the child processes
  2346.             "on the fly".  _c_v_c_o_v will not process coverage for
  2347.             these "on the fly" instrumented executables, because
  2348.             _c_v_m_o_n has not used the correct coverage instrumentation
  2349.             criteria.  This can cause performance and space
  2350.             overhead.
  2351.  
  2352.           +o IRIX 5.1 and later binaries are supported (no support
  2353.             for IRIX 4.0.X binaries) including shared and
  2354.             nonshared.
  2355.  
  2356.           +o Instrumentation criteria ccccoooouuuunnnnttttssss must at least include
  2357.             ----bbbbbbbbccccoooouuuunnnntttt.  For example, if user want to test function
  2358.             pointers the instrumentation file must contain the
  2359.             following line,
  2360.  
  2361.                 CCCCOOOOUUUUNNNNTTTTSSSS ----bbbbbbbbccccoooouuuunnnnttttssss ----ffffppppccccoooouuuunnnnttttssss
  2362.  
  2363.           +o The current model for running instrumented programs
  2364.             requires that a separate process (_c_v_m_o_n) monitor the
  2365.             programs that are undergoing coverage analysis.  This
  2366.             requires existing test scripts to be modified in the
  2367.             following manner:
  2368.  
  2369.  
  2370.  
  2371.  
  2372.  
  2373.  
  2374.  
  2375.  
  2376.  
  2377.  
  2378.  
  2379.  
  2380.                                   - 37 -
  2381.  
  2382.  
  2383.  
  2384.                 oooolllldddd ssssccccrrrriiiipppptttt::::
  2385.                    #### pppprrrrooooggggrrrraaaammmm aaaarrrrgggg1111 aaaarrrrgggg2222
  2386.                 nnnneeeewwww ssssccccrrrriiiipppptttt::::
  2387.                    #### ccccvvvvccccoooovvvv mmmmkkkktttteeeesssstttt ----ccccmmmmdddd """"pppprrrrooooggggrrrraaaammmm aaaarrrrgggg1111 aaaarrrrgggg2222"""" ----tttteeeessssttttnnnnaaaammmmeeee tttteeeesssstttt
  2388.                    #### ccccvvvvccccoooovvvv rrrruuuunnnntttteeeesssstttt tttteeeesssstttt
  2389.  
  2390.           +o There is potentially a large amount of data that can be
  2391.             captured when running multiple tests for large
  2392.             programs.  There are several options to the _r_u_n_t_e_s_t
  2393.             command that help manage this data.
  2394.  
  2395.             The -_n_o_a_r_c option is used to eliminate the capture of
  2396.             arc data in the experiment result (e.g., arc AB is
  2397.             equivalent to function A calls function B from line X).
  2398.             This significantly reduces the amount of overall count
  2399.             information for the test coverage result.
  2400.  
  2401.             The -_r_m_s_u_b option is used to retain the overall results
  2402.             for the top level test set or test group, not for the
  2403.             individual subtests.  There are several interactions of
  2404.             the -_r_m_s_u_b and -_s_u_m options worth noting.  If the
  2405.             -_r_m_s_u_b option is used, a subsequent "runtest" using the
  2406.             -_s_u_m option will not accumulate the counts data for
  2407.             these two runs.  In this case only the second run will
  2408.             be in the top level test set/test group.  The -_s_u_m
  2409.             option will sum up data only according to the count
  2410.             data that is in all the subtests currently and does not
  2411.             use the information in the top level test set or test
  2412.             group.  When using the -_s_u_m and -_r_m_s_u_b options
  2413.             together, the count data will be accumulated and the
  2414.             subtest data will be deleted.
  2415.  
  2416.             The -_c_o_m_p_r_e_s_s option is used to compress experiment
  2417.             database using standard utility _c_o_m_p_r_e_s_s.
  2418.  
  2419.             The -_b_i_t_c_o_u_n_t option is used to convert experiment
  2420.             database to 1-bit-per-count format in recording
  2421.             experiment so that it will save disk space up to 32
  2422.             times. However, count number for basic blocks and
  2423.             branch coverage information will be lost.
  2424.  
  2425.           +o Source highlighting for statement that cover multiple
  2426.             lines only highlights the last line. This is due to a
  2427.             limitation in symbol table data generated by the
  2428.             compiler.  For example, in the following source
  2429.             statement only the second line will be highlighted:
  2430.  
  2431.                     pppprrrriiiinnnnttttffff((((""""TTTThhhhiiiissss iiiissss aaaa tttteeeesssstttt ffffoooorrrr %%%%ssss aaaatttt %%%%dddd"""",,,,
  2432.             0000            tttteeeessssttttnnnnaaaammmmeeee,,,,wwwwhhhhiiiicccchhhhDDDDrrrriiiivvvveeee))));;;;
  2433.  
  2434.  
  2435.  
  2436.  
  2437.  
  2438.  
  2439.  
  2440.  
  2441.  
  2442.  
  2443.  
  2444.  
  2445.  
  2446.                                   - 38 -
  2447.  
  2448.  
  2449.  
  2450.           +o If the DSO cache directory has been removed, all the
  2451.             existing experiments may be invalid and _T_e_s_t_e_r may not
  2452.             work.
  2453.  
  2454.        5.8.2  _W_o_r_k_S_h_o_p__T_e_s_t_e_r__B_u_g_s
  2455.  
  2456.           +o Programs that use _a_r_g_v[_0] to build hardcoded filenames
  2457.             get confused by the renamed instrumented program (e.g.,
  2458.             <program> becomes <program_Instr>).
  2459.  
  2460.  
  2461.        5.9  _W_o_r_k_S_h_o_p__E_n_v_i_r_o_n_m_e_n_t
  2462.  
  2463.           +o If the colors of your WorkShop windows look too dark to
  2464.             read or conversely if they look completely washed out,
  2465.             there may be a discrepancy between the gamma value you
  2466.             are using and the value your X server is using.  The
  2467.             default value of gamma on installation is 1.7 but users
  2468.             running X programs may prefer a value of 1.0.
  2469.  
  2470.             Workaround: If you change your gamma value, by running
  2471.             the _g_a_m_m_a program (installed with _e_o_e_2._s_w._g_l_t_o_o_l_s),
  2472.             restart your X server.
  2473.  
  2474.           +o When starting up WorkShop, if you see the messages
  2475.  
  2476.             ////uuuussssrrrr////ssssbbbbiiiinnnn////ttttttttsssseeeessssssssiiiioooonnnn:::: CCCCaaaannnn''''tttt iiiinnnniiiitttt ttttyyyyppppeeee ddddaaaattttaaaabbbbaaaasssseeee....
  2477.             ////uuuussssrrrr////ssssbbbbiiiinnnn////ttttttttsssseeeessssssssiiiioooonnnn:::: eeeexxxxiiiittttiiiinnnngggg
  2478.             WWWWaaaarrrrnnnniiiinnnngggg:::: ttttttttsssseeeessssssssiiiioooonnnn:::: ssssiiiigggg____hhhhaaaannnnddddlllleeeerrrr:::: NNNNoooo cccchhhhiiiilllldddd pppprrrroooocccceeeesssssssseeeessss
  2479.             ////uuuussssrrrr////ssssbbbbiiiinnnn////ttttttttsssseeeessssssssiiiioooonnnn:::: CCCCaaaannnn''''tttt iiiinnnniiiitttt sssseeeerrrrvvvveeeerrrr....
  2480.             ttttttttsssseeeessssssssiiiioooonnnn:::: CCCCaaaannnn''''tttt iiiinnnniiiitttt ttttyyyyppppeeee ddddaaaattttaaaabbbbaaaasssseeee....
  2481.             ttttttttsssseeeessssssssiiiioooonnnn:::: eeeexxxxiiiittttiiiinnnngggg
  2482.             WWWWaaaarrrrnnnniiiinnnngggg:::: ttttttttsssseeeessssssssiiiioooonnnn:::: ssssiiiigggg____hhhhaaaannnnddddlllleeeerrrr:::: NNNNoooo cccchhhhiiiilllldddd pppprrrroooocccceeeesssssssseeeessss
  2483.             ttttttttsssseeeessssssssiiiioooonnnn:::: CCCCaaaannnn''''tttt iiiinnnniiiitttt sssseeeerrrrvvvveeeerrrr....
  2484.             TTTTttttuuuuttttiiiillll:::: CCCCaaaannnnnnnnooootttt ooooppppeeeennnn oooouuuurrrr TTTToooooooollllTTTTaaaallllkkkk pppprrrroooocccceeeessssssss iiiidddd
  2485.             ttttttttuuuuttttiiiillll:::: CCCCoooouuuullllddddnnnn''''tttt ccccoooonnnnnnnneeeecccctttt ttttoooo ttttttttsssseeeessssssssiiiioooonnnn sssseeeerrrrvvvviiiicccceeee((((ssss))))....
  2486.  
  2487.             check if you have the _C_E_P_A_T_H environment variable set.
  2488.             ToolTalk will use the _C_E_P_A_T_H variable for its
  2489.             definition of where the types database are located.
  2490.             WorkShop expects to find them in the default system
  2491.             database, /_e_t_c/_t_t/_t_y_p_e_s._x_d_r. Unsetting this environment
  2492.             variable will fix the startup problem.
  2493.  
  2494.           +o When starting up WorkShop, you may occassionally see
  2495.             the message
  2496.  
  2497.             ////uuuussssrrrr////ssssbbbbiiiinnnn////ttttttttsssseeeessssssssiiiioooonnnn:::: WWWWaaaarrrrnnnniiiinnnngggg:::: ccccoooouuuullllddddnnnn''''tttt aaaaccccqqqquuuuiiiirrrreeee XXXX sssseeeelllleeeeccccttttiiiioooonnnn
  2498.  
  2499.             ToolTalk displays this message when its internal state
  2500.             notes that someone else (i.e. another _t_t_s_e_s_s_i_o_n) has
  2501.  
  2502.  
  2503.  
  2504.  
  2505.  
  2506.  
  2507.  
  2508.  
  2509.  
  2510.  
  2511.  
  2512.                                   - 39 -
  2513.  
  2514.  
  2515.  
  2516.             already owned the X selection that it is trying to
  2517.             aquire.  This message is harmless and can be ignored.
  2518.  
  2519.           +o The network license mechanism used by WorkShop performs
  2520.             periodic checks to ensure that a license is available.
  2521.             Once obtained, a license is valid for 20 minutes. The
  2522.             license is validated every 10 minutes, and renewed for
  2523.             an additional 20 minutes if all is well. This process
  2524.             requires that WorkShop be actively running to be able
  2525.             to perform these checks. If the tool is unable to check
  2526.             the license server for 20 minutes, the license is lost,
  2527.             and the tool must be restarted to get a new license.
  2528.             Therefore, suspending a WorkShop process (using <Ctrl-
  2529.             Z>, for example) for more than a few minutes loses the
  2530.             tool's license.
  2531.  
  2532.           +o The WorkShop environment works with one configuration
  2533.             management system at a time. This affects all users
  2534.             running WorkShop on that machine.
  2535.  
  2536.           +o The default for string data is to display it as a hex
  2537.             address.  If you prefer the behavior of showing a
  2538.             string for _c_h_a_r *, you can set ****aaaauuuuttttooooSSSSttttrrrriiiinnnnggggFFFFoooorrrrmmmmaaaatttt to
  2539.             TTTTrrrruuuueeee in your ._X_d_e_f_a_u_l_t_s.  This will automatically
  2540.             change the result format from the default to string for
  2541.             _c_h_a_r * and _c_h_a_r <_a_r_r_a_y> expressions in the
  2542.             ExpressionView, VarBrowser, and DataBrowser.
  2543.  
  2544.  
  2545.  
  2546.  
  2547.  
  2548.  
  2549.  
  2550.  
  2551.  
  2552.  
  2553.  
  2554.  
  2555.  
  2556.  
  2557.  
  2558.  
  2559.  
  2560.  
  2561.  
  2562.  
  2563.  
  2564.  
  2565.  
  2566.  
  2567.  
  2568.  
  2569.  
  2570.  
  2571.  
  2572.  
  2573.  
  2574.  
  2575.